kicad-developers team mailing list archive
Mailing list archive
Re: Doxygen comment style
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.
On 6/15/2017 8:53 AM, Simon Richter wrote:
> 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.
> 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