RTEMS big comment conventions

[Andrew Butterfield]

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.

I am developing code (C and Promela) for the qualification activity,
and want to start to get this right - so which should I use?

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/
--------------------------------------------------------------------