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 : [email protected] > Unsubscribe : https://launchpad.net/~kicad-developers > More help : https://help.launchpad.net/ListHelp > _______________________________________________ Mailing list: https://launchpad.net/~kicad-developers Post to : [email protected] Unsubscribe : https://launchpad.net/~kicad-developers More help : https://help.launchpad.net/ListHelp
