kicad-developers team mailing list archive

[Wayne Stambaugh <stambaughw@xxxxxxxxx>]

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.

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