Hi Dave, Looks great! My only comment on the style is that for functions, the comment with description and args/return should always be in the header file, or at the top of a file if it's a local/static function. The only comments that should appear near the definition of a function should be implementation details, which may not even be doxygen-ized.
-Eric On Wed, Jun 17, 2009 at 09:42:06AM -0400, David Shrewsbury wrote: > All, > > I've begun a section in the wiki describing *one possible style* for our > Doxygenated comments in the code: > > http://drizzle.org/wiki/Coding_Standards#Comments > > Please keep these ideas in mind: > > 1) This was created in order to begin discussion on comment style. It is > not yet the recommended style. > > 2) Doxygen allows for many styles of commenting. No Drizzler was consulted > for this particular style; it is just my personal preference. I expect > others to > change the recommendations as it is discussed and a final style is settled > on > (if we decide on only 1 style). For example, @brief and @details are not > always > needed since we *should* be using the JAVADOC_AUTOBRIEF Doxygen option. > > 3) There are likely pieces missing from what I've started. Feel free to > add them. > > 4) I would like to make the recommendation that, as you work, if you touch > a > class or function, you should be a responsible Drizzler and consider > yourself > responsible for modifying/adding the comments to fit the selected Doxygen > commenting style. > > -Dave > _______________________________________________ > Mailing list: https://launchpad.net/~drizzle-discuss > Post to : [email protected] > Unsubscribe : https://launchpad.net/~drizzle-discuss > More help : https://help.launchpad.net/ListHelp _______________________________________________ Mailing list: https://launchpad.net/~drizzle-discuss Post to : [email protected] Unsubscribe : https://launchpad.net/~drizzle-discuss More help : https://help.launchpad.net/ListHelp
