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:
parent
f9b054242e
commit
1d1da9e31b
1 changed files with 30 additions and 15 deletions
|
@ -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
|
||||||
|
|
Loading…
Reference in a new issue