[<prev] [next>] [<thread-prev] [day] [month] [year] [list]
Message-ID: <170783464515.398.17242273988924436595.tip-bot2@tip-bot2>
Date: Tue, 13 Feb 2024 14:30:45 -0000
From: "tip-bot2 for Borislav Petkov (AMD)" <tip-bot2@...utronix.de>
To: linux-tip-commits@...r.kernel.org
Cc: "Borislav Petkov (AMD)" <bp@...en8.de>,
Thomas Gleixner <tglx@...utronix.de>, x86@...nel.org,
linux-kernel@...r.kernel.org
Subject:
[tip: x86/misc] Documentation/maintainer-tip: Add C++ tail comments exception
The following commit has been merged into the x86/misc branch of tip:
Commit-ID: 7dd0a21ccb5a937ca9f798afad34de4ba030f8d4
Gitweb: https://git.kernel.org/tip/7dd0a21ccb5a937ca9f798afad34de4ba030f8d4
Author: Borislav Petkov (AMD) <bp@...en8.de>
AuthorDate: Mon, 12 Feb 2024 16:41:42 +01:00
Committer: Borislav Petkov (AMD) <bp@...en8.de>
CommitterDate: Tue, 13 Feb 2024 13:19:40 +01: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@...en8.de>
Reviewed-by: Thomas Gleixner <tglx@...utronix.de>
Link: https://lore.kernel.org/r/20240130193102.GEZblOdor_bzoVhT0f@fat_crate.local
---
Documentation/process/maintainer-tip.rst | 30 ++++++++++++++++++++++-
1 file changed, 29 insertions(+), 1 deletion(-)
diff --git a/Documentation/process/maintainer-tip.rst b/Documentation/process/maintainer-tip.rst
index 7993592..497bb39 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
Powered by blists - more mailing lists