Jay, I prefer C-style comments too. But there is no C-style comment for a "brief" comment _after_ data members. (Brief comments on data members will appear in the Public Attributes section at the top of the html file. Detailed comments appear in the description of the data member lower in the html file). The /**< style is for a detailed comment after the member (and no "brief" equivalent). So I chose the C++ style. Feel free to update the wiki though if that's what we should go with.
-Dave On Sun, Jun 21, 2009 at 9:57 AM, Jay Pipes <[email protected]> wrote: > Eric Day wrote: > >> 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. >> > > ++ > > Also, I tend to prefer the: > > int my_var; /**< my_var does xxxx */ > > member variable comment versus this style: > > int my_var; ///< my_var does xxxx > > Since we generally use the /* */ comment style everywhere and discourage > the use of the // C++-specific style. > > Cheers, > > Jay > > > -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 >> > >
_______________________________________________ Mailing list: https://launchpad.net/~drizzle-discuss Post to : [email protected] Unsubscribe : https://launchpad.net/~drizzle-discuss More help : https://help.launchpad.net/ListHelp
