On Wed, Mar 22, 2017 at 04:08:40PM -0400, Wayne Stambaugh wrote: > On 3/22/2017 1:14 PM, Chris Pavlina wrote: > > On Wed, Mar 22, 2017 at 01:05:48PM -0400, Wayne Stambaugh wrote: > >> 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. > > > > May I ask why? IMO one giant commit would be the least noisy, cleanest > > option. It's a single item in the history that only has to be looked at > > once. Also it ensures some sort of consistency - my experience is that > > when we do things "as we go" we just end up forgetting to and end up > > with an ugly mix. > > Give me a chance to take a look at the difference in the doxygen output > just so I have a better understanding of why we should do this. My > primary concern is merge conflicts. If you change every or nearly every > header file to remove the redundant function declarations, us poor > hapless developers who have commits queued up will most likely get bit > pretty hard.
Nah, git usually handles simple merges like that very well. I doubt it'll be an issue. At best you'll have to help it by dropping changes for any functions you've deleted in private branches. Very routine merge, honestly. > > > > >> > >> 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 _______________________________________________ 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