Commit 7dd0a21c authored by Borislav Petkov (AMD)'s avatar Borislav Petkov (AMD)

Documentation/maintainer-tip: Add C++ tail comments exception

Document when C++-style, tail comments should be used.
Signed-off-by: default avatarBorislav Petkov (AMD) <bp@alien8.de>
Reviewed-by: default avatarThomas Gleixner <tglx@linutronix.de>
Link: https://lore.kernel.org/r/20240130193102.GEZblOdor_bzoVhT0f@fat_crate.local
parent b37bf5ef
......@@ -480,7 +480,7 @@ Multi-line comments::
* 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
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? */
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:
Comments should be added where the operation is not obvious. Documenting
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment