Kernel/linux
1
0
Fork 0
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2025-01-01 10:43:43 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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:
Borislav Petkov (AMD) 2024-02-12 16:41:42 +01:00
parent b37bf5ef17
commit 7dd0a21ccb
1 changed files with 29 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
Documentation/process/maintainer-tip.rst
View File

@ -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