kicad-developers team mailing list archive

[Wayne Stambaugh <stambaughw@xxxxxxxxx>]

Simon,

This makes sense to me.  I spent some time a while back looking at the
Doxygen output and came to the same conclusion.  I have a few Doxygen
comments of my own that follow this formatting so you are not alone.  I
will update the coding policy when I get a chance.  All developers,
please consider this the notification of the changes to the Doxygen
commenting section of the coding policy.  Please do not consider this a
call to change every single Doxygen comment and bombard me with a bunch
of patches. ;)  I'm OK with updating them as we go.

Cheers,

Wayne

On 6/15/2017 8:53 AM, Simon Richter wrote:
> Hi,
> 
> the current coding standard says that function comments should look like
> 
> /**
>  * Function foo
>  *
>  * blablabla
>  */
> 
> Since doxygen uses the first line as the brief description, the class
> overview ends up looking like this:
> 
> | foo | Function foo |
> | bar | Function bar |
> 
> That is not really helpful, in my opinion, so I've violated the policy
> in a few places already, and seem to have gotten away with it.
> 
> Can we change the policy as well though?
> 
>   The first sentence should briefly describe the function. It should
>   fit into a single line and be written in the infinitive form, without
>   a subject, e.g. "Get the width of the outline" or "Re-run DRC". The
>   brief description should be understandable on its own, as it is used
>   in the class index.
> 
>    Simon
> 
> 
> 
> _______________________________________________
> 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
>