You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Some block comments in the code, but not others, start with "###*". Since your attention to detail is staggering, I was wondering if there was a particular meaning behind that - especially given the choice of pass-through comment blocks, vs. the regular # - or if I shouldn't look too much into that as I dive into the code.
The text was updated successfully, but these errors were encountered:
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.
Some block comments in the code, but not others, start with "###*". Since your attention to detail is staggering, I was wondering if there was a particular meaning behind that - especially given the choice of pass-through comment blocks, vs. the regular
#
- or if I shouldn't look too much into that as I dive into the code.The text was updated successfully, but these errors were encountered: