<div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, Oct 22, 2020 at 6:07 AM Andrew Butterfield <<a href="mailto:Andrew.Butterfield@scss.tcd.ie">Andrew.Butterfield@scss.tcd.ie</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Dear all,<br>
<br>
In the RTEMS Software Engineering manual, Sec 6.3.2.1<br>
<a href="https://docs.rtems.org/branches/master/eng/coding-80cols.html#breaking-long-lines" rel="noreferrer" target="_blank">https://docs.rtems.org/branches/master/eng/coding-80cols.html#breaking-long-lines</a><br>
it recommends excessively long comments be broken as follows:<br>
<br>
/* first line<br>
* second line<br>
* third, and in this case last line */<br></blockquote><div><br></div><div>I don't think that should be used. I don't know that we ever allowed that. </div><div>Maybe that's a formatting mistake in the documentation. That part of the</div><div>engineering guide was converted from the wiki to Sphinx by students.</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
In Sec 6.3.5.2<br>
<a href="https://docs.rtems.org/branches/master/eng/coding-file-hdr.html#fileheadercopyright" rel="noreferrer" target="_blank">https://docs.rtems.org/branches/master/eng/coding-file-hdr.html#fileheadercopyright</a><br>
we see a copyright and license header which uses the following format convention:<br>
<br>
/**<br>
* first line<br>
* second line<br>
* third, and in this case last line <br>
*/<br></blockquote><div><br></div><div>The "/**" says this is a comment block to be picked up by Doxygen. </div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
Most RTEMS code I look at seems to follow this second approach,<br>
or the following with only one asterisk on the first line<br>
- particularly the comments that are used to generate Doxygen docs.<br>
<br>
/*<br>
* first line<br>
* second line<br>
* third, and in this case last line <br>
*/<br></blockquote><div><br></div><div>This is probably most comment for copyright and license blocks which</div><div>should not be picked up in the Doxygen. But I know it is also used for</div><div>inline comments in code also not intended for Doxygen.</div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
PS - I prefer this secon/third approach, particularly when the large comment<br>
immediately precedes code.<br>
<br>
I am developing code (C and Promela) for the qualification activity,<br>
and want to start to get this right - so which should I use?<br></blockquote><div><br></div><div>Please not the first. Looks like a documentation bug to me. </div><div><br></div><div>Please feel free to submit a patch and ticket for this. </div><div><br></div><div>--joel </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
Regards,<br>
Andrew Butterfield<br>
<br>
--------------------------------------------------------------------<br>
Andrew Butterfield Tel: +353-1-896-2517 Fax: +353-1-677-2204<br>
Lero@TCD, Head of Software Foundations & Verification Research Group<br>
School of Computer Science and Statistics,<br>
Room G.39, O'Reilly Institute, Trinity College, University of Dublin<br>
<a href="http://www.scss.tcd.ie/Andrew.Butterfield/" rel="noreferrer" target="_blank">http://www.scss.tcd.ie/Andrew.Butterfield/</a><br>
--------------------------------------------------------------------<br>
<br>
_______________________________________________<br>
devel mailing list<br>
<a href="mailto:devel@rtems.org" target="_blank">devel@rtems.org</a><br>
<a href="http://lists.rtems.org/mailman/listinfo/devel" rel="noreferrer" target="_blank">http://lists.rtems.org/mailman/listinfo/devel</a><br>
</blockquote></div></div>