kicad-developers team mailing list archive

[Chris Pavlina <pavlina.chris@xxxxxxxxx>]

I really hate @brief and @details. Doxygen can do that automatically,
making the brief docstring the first sentence and the details one the
whole text. It makes for a doc comment that is much more readable in the
header itself, which is honestly how I read them most of the time.

On Wed, Mar 22, 2017 at 11:11:35AM -0500, Jon Evans wrote:
> 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
> >