RTEMS big comment conventions

[Gedare Bloom]

Hi Andrew,

On Thu, Oct 22, 2020 at 5:07 AM Andrew Butterfield
<Andrew.Butterfield at scss.tcd.ie> wrote:
>
> Dear all,
>
> In the RTEMS Software Engineering manual, Sec 6.3.2.1
> https://docs.rtems.org/branches/master/eng/coding-80cols.html#breaking-long-lines
> it recommends excessively long comments be broken as follows:
>
> /* first line
>  * second line
>  * third, and in this case last line */
>
> In Sec 6.3.5.2
> https://docs.rtems.org/branches/master/eng/coding-file-hdr.html#fileheadercopyright
> we see a copyright and license header which uses the following format convention:
>
> /**
>  * first line
>  * second line
>  * third, and in this case last line
>  */
>
> Most RTEMS code I look at seems to follow this second approach,
> or the following with only one asterisk on the first line
> - particularly the comments that are used to generate Doxygen docs.
>
> /*
>  * first line
>  * second line
>  * third, and in this case last line
>  */
>
> PS - I prefer this secon/third approach, particularly when the large comment
> immediately precedes code.
>
Correct, the /** is specifically meant for doxygen. (It is the
"javadoc" style of comments that doxygen can parse.)

A little bit of grep/regex suggests that inside of cpukit/score we have:
3679 occurrences of /* or /** with */ on the same line
2524 occurrences of /* or /** with no */ on the same line
124 occurrences of /* or /** with some trailing characters and no */
on same line
2400 occurrences of /* or /** with no trailing characters on the same line

2524 occurrences of */ with no /* on the same line (good, that matches
from above!)
35 occurrences of */ with preceding non-whitespace characters.

So your observation is certainly confirmed. We have not been
particular about the comment style, but I think usually we see
two-liners with
/* first line
 * second line */
While longer than two-lines tends to follow that
/*
 * first
 * second
 * third
 * etc.
 */
pattern.

Use the /** for doxygen comments. I think it would be fine to go with
the empty first/last line. That does seem to be the precedent.

> I am developing code (C and Promela) for the qualification activity,

Our style guidelines for C code is mainly for the code that is
internal to RTEMS. We are fine with any self-consistent style in other
contributions (such as BSPs) although code that is meant to be added
to rtems.git should strive to follow our style.

We are looking at how to make style more easily enforced and
maintained by tooling.

> and want to start to get this right - so which should I use?

For standalone tools it is really your choice. We would prefer
adoption of an easily maintained style consistent with some kind of
sane default.

>
> Regards,
>   Andrew Butterfield
>
> --------------------------------------------------------------------
> Andrew Butterfield     Tel: +353-1-896-2517     Fax: +353-1-677-2204
> Lero at TCD, Head of Software Foundations & Verification Research Group
> School of Computer Science and Statistics,
> Room G.39, O'Reilly Institute, Trinity College, University of Dublin
>                          http://www.scss.tcd.ie/Andrew.Butterfield/
> --------------------------------------------------------------------
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel