mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
synced 2024-09-27 12:57:53 +00:00
Documentation/maintainer-tip: Add C++ tail comments exception
Document when C++-style, tail comments should be used. Signed-off-by: Borislav Petkov (AMD) <bp@alien8.de> Reviewed-by: Thomas Gleixner <tglx@linutronix.de> Link: https://lore.kernel.org/r/20240130193102.GEZblOdor_bzoVhT0f@fat_crate.local
This commit is contained in:
parent
b37bf5ef17
commit
7dd0a21ccb
1 changed files with 29 additions and 1 deletions
|
@ -480,7 +480,7 @@ Multi-line comments::
|
||||||
* Larger multi-line comments should be split into paragraphs.
|
* Larger multi-line comments should be split into paragraphs.
|
||||||
*/
|
*/
|
||||||
|
|
||||||
No tail comments:
|
No tail comments (see below):
|
||||||
|
|
||||||
Please refrain from using tail comments. Tail comments disturb the
|
Please refrain from using tail comments. Tail comments disturb the
|
||||||
reading flow in almost all contexts, but especially in code::
|
reading flow in almost all contexts, but especially in code::
|
||||||
|
@ -501,6 +501,34 @@ No tail comments:
|
||||||
/* This magic initialization needs a comment. Maybe not? */
|
/* This magic initialization needs a comment. Maybe not? */
|
||||||
seed = MAGIC_CONSTANT;
|
seed = MAGIC_CONSTANT;
|
||||||
|
|
||||||
|
Use C++ style, tail comments when documenting structs in headers to
|
||||||
|
achieve a more compact layout and better readability::
|
||||||
|
|
||||||
|
// eax
|
||||||
|
u32 x2apic_shift : 5, // Number of bits to shift APIC ID right
|
||||||
|
// for the topology ID at the next level
|
||||||
|
: 27; // Reserved
|
||||||
|
// ebx
|
||||||
|
u32 num_processors : 16, // Number of processors at current level
|
||||||
|
: 16; // Reserved
|
||||||
|
|
||||||
|
versus::
|
||||||
|
|
||||||
|
/* eax */
|
||||||
|
/*
|
||||||
|
* Number of bits to shift APIC ID right for the topology ID
|
||||||
|
* at the next level
|
||||||
|
*/
|
||||||
|
u32 x2apic_shift : 5,
|
||||||
|
/* Reserved */
|
||||||
|
: 27;
|
||||||
|
|
||||||
|
/* ebx */
|
||||||
|
/* Number of processors at current level */
|
||||||
|
u32 num_processors : 16,
|
||||||
|
/* Reserved */
|
||||||
|
: 16;
|
||||||
|
|
||||||
Comment the important things:
|
Comment the important things:
|
||||||
|
|
||||||
Comments should be added where the operation is not obvious. Documenting
|
Comments should be added where the operation is not obvious. Documenting
|
||||||
|
|
Loading…
Reference in a new issue