I really hate @brief and @details. Doxygen can do that automatically, making the brief docstring the first sentence and the details one the whole text. It makes for a doc comment that is much more readable in the header itself, which is honestly how I read them most of the time.
On Wed, Mar 22, 2017 at 11:11:35AM -0500, Jon Evans wrote: > Hi Chris, > > I agree with this and would also suggest that there are more Doxygen tags > we can use if desired. > In fact, I use a plugin for my editor that generates Doxygen templates > automatically if I type "/**<Enter>" above a line of code: > > /** > * @brief [brief description] > * @details [long description] > * > * @param aColor [description] > * @return [description] > */ > > There is also the "@see" tag which is quite useful > > -Jon > > On Wed, Mar 22, 2017 at 10:41 AM, Chris Pavlina <pavlina.ch...@gmail.com> > wrote: > > > Hi all and mostly Wayne, > > > > I notice that a lot of our older documentation comments redundantly list > > the name of the function they document: > > > > /** > > * Function IsVoid > > * @return true if the field value is void (no text in this field) > > */ > > bool IsVoid() const > > > > I don't see any purpose for this redundancy - Doxygen doesn't use it, > > the formatted documentation actually looks better without it. It seems > > unnecessary to me, and a bit ugly: https://misc.c4757p.com/isvoid.png > > > > (Not to mention that this is a method, not a function ;) > > > > I'd document this method thus: > > > > /** > > * @return true iff the field value is void (i.e. has no text) > > */ > > bool IsVoid() const > > > > Is there any reason to keep these? > > > > -- > > Chris > > > > _______________________________________________ > > Mailing list: https://launchpad.net/~kicad-developers > > Post to : kicad-developers@lists.launchpad.net > > Unsubscribe : https://launchpad.net/~kicad-developers > > More help : https://help.launchpad.net/ListHelp > > _______________________________________________ Mailing list: https://launchpad.net/~kicad-developers Post to : kicad-developers@lists.launchpad.net Unsubscribe : https://launchpad.net/~kicad-developers More help : https://help.launchpad.net/ListHelp
