kicad-developers team mailing list archive

[John Beard <john.j.beard@xxxxxxxxx>]

I think these are useless - the function name is right there anyway
unless the comment is absolutely enormous. These are just places for
doc-rot to creep if the function name changes.

I sometimes add them, but usually just to maintain consistency in a file.

Over 400 classes have a similar "* Class [A-Z]" in their comment too.

On Wed, Mar 22, 2017 at 11:41 PM, Chris Pavlina <pavlina.chris@xxxxxxxxx> 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
>
> (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?
>
> --
> Chris
>
> _______________________________________________
> 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