A lot of this is a product of habit and copy & paste. It's not uncommon for derived classes to have the same header doc comments as the base class even though this is not necessary either. I'm OK with changing this as we update headers. I would rather avoid the one giant commit with all of the doc comments modified.
On 3/22/2017 11:41 AM, Chris Pavlina 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 What's the difference in the doxygen output when the method name isn't in the doc comment? I've never really looked at it that closely. > > (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? > _______________________________________________ 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
