On Thu, Oct 22, 2020 at 6:07 AM Andrew Butterfield < andrew.butterfi...@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@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@rtems.org > http://lists.rtems.org/mailman/listinfo/devel >
_______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
