kicad-developers team mailing list archive

[Jon Evans <jon@xxxxxxxxxxxxx>]

Yes I agree with you here, I need to figure out how to update my template
because I always end up deleting those.

On Wed, Mar 22, 2017 at 11:14 AM, Chris Pavlina <pavlina.chris@xxxxxxxxx>
wrote:

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