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