← Back to team overview

kicad-developers team mailing list archive

Re: Doxygen comment style



That seems eminently sensible, and matches the policy active in other large projects I'm involved with that use doxygen. I would only emphasise that the first line is of limited length: no 200+ character brief descriptions!

In general I would encourage the policy to have both positive and negative examples, which often help to clarify what is meant for non-native readers.


On 15/06/2017 13:53, 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