kicad-developers team mailing list archive

[Chris Pavlina <pavlina.chris@xxxxxxxxx>]

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.

> 
> 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