docs/grub-dev: Change comments rules

Current comments forms are annoying, so, some of them are disallowed
starting from now. New rules are more flexible and mostly aligned
with, e.g., Linux kernel comments rules.

Signed-off-by: Daniel Kiper <daniel.kiper@oracle.com>
Reviewed-by: Vladimir Serbinenko <phcoder@google.com>
This commit is contained in:
Daniel Kiper 2019-03-29 16:11:04 +01:00 committed by Vincent Batts
parent f9b054242e
commit 1d1da9e31b

View file

@ -183,38 +183,44 @@ If a macro is global, its name must be prefixed with GRUB_ and must consist of o
@section Comments @section Comments
All comments shall be C-style comments, of the form @samp{/* @dots{} */}. All comments shall be C-style comments, of the form @samp{/* @dots{} */}.
A comment can be placed immediately preceding the entity it describes or it
Comments shall be placed only on a line by themselves. They shall not be placed together with code, variable declarations, or other non-comment entities. A comment should be placed immediately preceding the entity it describes. can be placed together with code, variable declarations, or other non-comment
entities. However, it is recommended to not mix various forms especially in
types/structs descriptions.
Acceptable: Acceptable:
@example @example
/* The page # that is the front buffer. */ /* The page # that is the front buffer. */
int displayed_page; int displayed_page;
/* The page # that is the back buffer. */
int render_page;
@end example @end example
Unacceptable:
@example @example
int displayed_page; /* The page # that is the front buffer. */ int render_page; /* The page # that is the back buffer. */
int render_page; /* The page # that is the back buffer. */
@end example @end example
@node Multi-Line Comments @node Multi-Line Comments
@section Multi-Line Comments @section Multi-Line Comments
Comments spanning multiple lines shall be formatted with all lines after the first aligned with the first line. Comments spanning multiple lines shall be formatted with all lines after the
first aligned with the first line. Asterisk characters should be repeated at
Asterisk characters should not be repeated a the start of each subsequent line. the start of each subsequent line.
Acceptable: Acceptable:
@example @example
/* This is a comment /*
which spans multiple lines. * This is a comment
It is long. */ * which spans multiple lines.
* It is long.
*/
@end example @end example
Unacceptable: Unacceptable:
@example
/* This is a comment
which spans multiple lines.
It is long. */
@end example
@example @example
/* /*
* This is a comment * This is a comment
@ -222,7 +228,16 @@ Unacceptable:
* It is long. */ * It is long. */
@end example @end example
The opening @samp{/*} and closing @samp{*/} should be placed together on a line with text. @example
/* This is a comment
* which spans multiple lines.
* It is long.
*/
@end example
In particular first unacceptable form makes comment difficult to distinguish
from the code itself. Especially if it contains the code snippets and/or is
long. So, its usage is disallowed.
@node Finding your way around @node Finding your way around
@chapter Finding your way around @chapter Finding your way around