Messages in this thread Patch in this message | | | Date | Mon, 12 Feb 2024 16:43:47 +0100 | From | Borislav Petkov <> | Subject | Re: [patch v5 06/19] x86/cpu: Provide a sane leaf 0xb/0x1f parser |
| |
On Mon, Feb 12, 2024 at 04:08:31PM +0100, Thomas Gleixner wrote: > This really makes my eyes bleed.
From: Borislav Petkov (AMD) <bp@alien8.de> Date: Mon Feb 12 16:41:42 2024 +0100
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>
diff --git a/Documentation/process/maintainer-tip.rst b/Documentation/process/maintainer-tip.rst index 799359231b7f..497bb39727c8 100644 --- a/Documentation/process/maintainer-tip.rst +++ b/Documentation/process/maintainer-tip.rst @@ -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
-- Regards/Gruss, Boris.
https://people.kernel.org/tglx/notes-about-netiquette
| |