sergiotarxz/nuttx
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Documentation/NuttXCCodingStandard.html: Fix description of comments on the right.

Browse Source 
Documentation/NuttXCCodingStandard.html:
  - Fix a typo:  "be aligned so that the comment begins in the same comment on each line." Of course that should have been column.
  - Update a coding standard requirement.  With regard to Comments to the Right of Statements, the document said:  "If such comments are used, they should ... fit on one line."  This is not true any more.  In common practice (include the checks in nxstyle), comments to the right of statements may be continued in the following line.  The standard way of continuing such comments was also documented.
    In this case the coding standard actually contradicted iteself since first it says the that the comments to the right must fit on one line, but later illustrates (without description) how to continue a long right hand comment on the following line.

Documents/style.css:  It appears that a variable width font was being used for <pre> and <code>, that was really screwing up the presentation, especially in the coding standared where there are many examples illustrating correct vertical alignment.  The font type "Bitstream Vera Sans Mono" was replaced with "courier" for <pre> and <code>
This commit is contained in:
Gregory Nutt 2020-05-19 18:32:13 -06:00 committed by Xiang Xiao
parent ca8585e8e7
commit 611aa8b998
2 changed files with 11 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
Documentation/NuttXCCodingStandard.html
View File

@ -87,7 +87,7 @@
<h1><big><font color="#3c34ec">
<i>NuttX C Coding Standard</i>
</font></big></h1>
<p>Last Updated: February 2, 2020</p>
<p>Last Updated: May 19, 2020</p>
</td>
</tr>
</table>
@ -568,7 +568,7 @@
<p>
<b>Comments to the Right of Statements</b>.
Comments to the right of statements in C source files are discouraged.
If such comments are used, they should be (1) very short so that they do not exceed the line width (typically 78 characters), (2) fit on one line, and (3) be aligned so that the comment begins in the same comment on each line.
If such comments are used, they should be (1) very short so that they do not exceed the line width (typically 78 characters), (2) aligned so that the comment begins in the same column on each line.
</p>
<center><table width="60%" border=1>
<tr><td bgcolor="white">
@ -660,6 +660,13 @@ struct animals_s
Comments on the right of statements or data definitions must be short and fit on the same line without exceeding the maximum line length.
If a longer comment is needed, then it should appear above the statement of definition rather than to the right of the definition.
</p>
<p>
<b>Breaking Long Comments to the Right of Statements</b>
Breaking long comments to the right of statements is acceptable as well, but not encouraged.
In this case the comment must be begin on the first line of the multi-line, right-hand comment with the opening comment delimiter (/*).
The following lines of the multi-line, right hand comment must be with an asterisk (*) aligned in the same column as the asterisk in the preceding line.
The closing comment delimiter must lie on the <i>same</i> line with the asterisk.
</p>
<center><table width="60%" border=1>
<tr><td bgcolor="white">
<p><font color="red"><b>Incorrect</b></p>

4
Documentation/style.css
View File

@ -18,7 +18,7 @@ a:hover
code
{
font-family: "Bitstream Vera Sans Mono";
font-family: "courier";
color: #2b4893;
background: #f4f4f4;
padding-left: 0.25em;
@ -27,7 +27,7 @@ code
pre
{
font-family: "Bitstream Vera Sans Mono";
font-family: "courier";
background: #f4f4f4;
padding: 1em;
}