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

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

Documentation/process/maintainer-tip.rst

+29 −1
Original line number Diff line number Diff line
@@ -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