kicad-developers team mailing list archive

[Jon Evans <jon@xxxxxxxxxxxxx>]

Hi Chris,

I agree with this and would also suggest that there are more Doxygen tags
we can use if desired.
In fact, I use a plugin for my editor that generates Doxygen templates
automatically if I type "/**<Enter>" above a line of code:

/**
 * @brief [brief description]
 * @details [long description]
 *
 * @param aColor [description]
 * @return [description]
 */

There is also the "@see" tag which is quite useful

-Jon

On Wed, Mar 22, 2017 at 10:41 AM, 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
>