RTEMS big comment conventions

[Joel Sherrill]

On Thu, Oct 22, 2020 at 6: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 */
>

I don't think that should be used. I don't know that we ever allowed that.
Maybe that's a formatting mistake in the documentation. That part of the
engineering guide was converted from the wiki to Sphinx by students.


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

The "/**" says this is a comment block to be picked up by Doxygen.



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

This is probably most comment for copyright and license blocks which
should not be picked up in the Doxygen. But I know it is also used for
inline comments in code also not intended for Doxygen.

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

Please not the first. Looks like a documentation bug to me.

Please feel free to submit a patch and ticket for this.

--joel

>
> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20201022/2c7c0460/attachment.html>