kicad-developers team mailing list archive

[Wayne Stambaugh <stambaughw@xxxxxxxxx>]

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