Any particular meaning behind the asterisks after block comments? about meteor-restivus

[kahmali]

Ultimately, my goal is to JSDoc the entire Restivus API, and apiDoc any autogenerated endpoints (both of which are on my makeshift roadmap). I come from the school of thought that another developer shouldn't have to understand your implementation just to work with your API. For JSDoc, I'm under the impression that the * is necessary after the opening ### of a block for parsing of those comments. Comments without that would be ignored. It isn't required in apiDoc, but it doesn't interfere with the output, so I figure it would be best to just keep things consistent between all block comments (which I clearly haven't done here :) ).

The reason that some methods have it and some don't is completely arbitrary at this point. Every public method (and maybe even some of the handy or more complex "private" methods) should be properly documented (to make journeys such as the one you are about to embark on much easier). This is, admittedly, the first open source project I've been a part of, and sometimes I struggle between maintaining balance in the level of documentation I'm comfortable with and my users' needs for updates and bug fixes. That causes some of these inconsistencies to break through. I just need to make an effort to generate the docs and go through and add all the necessary detail (e.g. @params, @returns, etc.). Now that it appears I have another active contributor, I will make an effort to do this asap.

[kahmali]

I filed issue #54 to make the comments consistent. Thanks for raising the question! Any discussion on this can continue over there now.