kicad-developers team mailing list archive

[Chris Pavlina <pavlina.chris@xxxxxxxxx>]

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@xxxxxxxxxxxxxxxxxxx
> >> Unsubscribe : https://launchpad.net/~kicad-developers
> >> More help   : https://help.launchpad.net/ListHelp