Message-ID: <20250509203430.3448-2-adobriyan@gmail.com>
Date: Fri,  9 May 2025 23:34:23 +0300
From: Alexey Dobriyan <adobriyan@...il.com>
To: corbet@....net
Cc: workflows@...r.kernel.org,
	linux-kernel@...r.kernel.org,
	Alexey Dobriyan <adobriyan@...il.com>
Subject: [PATCH 2/9] CodingStyle: delete explicit numbering

All _real_ documentation systems have a way to number
chapters/sections/subsections automatically.

I haven't found a way to do it in this reST thingy so keep them
unnumbered for the time being.

Signed-off-by: Alexey Dobriyan <adobriyan@...il.com>
---
 Documentation/process/coding-style.rst | 100 ++++++++++++-------------
 1 file changed, 50 insertions(+), 50 deletions(-)

diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 19d2ed47ff79..a4fbe45c3eb9 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -15,8 +15,8 @@ and NOT read it.  Burn them, it's a great symbolic gesture.
 Anyway, here goes:
 
 
-1) Indentation
---------------
+Indentation
+-----------
 
 Tabs are 8 characters, and thus indentations are also 8 characters.
 There are heretic movements that try to make indentations 4 (or even 2!)
@@ -95,8 +95,8 @@ used for indentation, and the above example is deliberately broken.
 Get a decent editor and don't leave whitespace at the end of lines.
 
 
-2) Breaking long lines and strings
-----------------------------------
+Breaking long lines and strings
+-------------------------------
 
 Coding style is all about readability and maintainability using commonly
 available tools.
@@ -117,8 +117,8 @@ However, never break user-visible strings such as printk messages because
 that breaks the ability to grep for them.
 
 
-3) Placing Braces and Spaces
-----------------------------
+Placing Braces and Spaces
+-------------------------
 
 The other issue that always comes up in C styling is the placement of
 braces.  Unlike the indent size, there are few technical reasons to
@@ -231,8 +231,8 @@ Also, use braces when a loop contains more than a single simple statement:
 			do_something();
 	}
 
-3.1) Spaces
-***********
+Spaces
+******
 
 Linux kernel style for use of spaces depends (mostly) on
 function-versus-keyword usage.  Use a space after (most) keywords.  The
@@ -303,8 +303,8 @@ of patches, this may make later patches in the series fail by changing their
 context lines.
 
 
-4) Naming
----------
+Naming
+------
 
 C is a Spartan language, and your naming conventions should follow suit.
 Unlike Modula-2 and Pascal programmers, C programmers do not use cute
@@ -356,8 +356,8 @@ specification that mandates those terms. For new specifications
 translate specification usage of the terminology to the kernel coding
 standard where possible.
 
-5) Typedefs
------------
+Typedefs
+--------
 
 Please don't use things like ``vps_t``.
 It's a **mistake** to use typedef for structures and pointers. When you see a
@@ -440,8 +440,8 @@ In general, a pointer, or a struct that has elements that can reasonably
 be directly accessed should **never** be a typedef.
 
 
-6) Functions
-------------
+Functions
+---------
 
 Functions should be short and sweet, and do just one thing.  They should
 fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
@@ -480,8 +480,8 @@ closing function brace line.  E.g.:
 	}
 	EXPORT_SYMBOL(system_is_up);
 
-6.1) Function prototypes
-************************
+Function prototypes
+*******************
 
 In function prototypes, include parameter names with their data types.
 Although this is not required by the C language, it is preferred in Linux
@@ -523,8 +523,8 @@ below, compared to the **declaration** example above)::
 	...
  }
 
-7) Centralized exiting of functions
------------------------------------
+Centralized exiting of functions
+--------------------------------
 
 Albeit deprecated by some people, the equivalent of the goto statement is
 used frequently by compilers in form of the unconditional jump instruction.
@@ -595,8 +595,8 @@ fix for this is to split it up into two error labels ``err_free_bar:`` and
 Ideally you should simulate errors to test all exit paths.
 
 
-8) Commenting
--------------
+Commenting
+----------
 
 Comments are good, but there is also a danger of over-commenting.  NEVER
 try to explain HOW your code works in a comment: it's much better to
@@ -635,8 +635,8 @@ multiple data declarations).  This leaves you room for a small comment on each
 item, explaining its use.
 
 
-9) You've made a mess of it
----------------------------
+You've made a mess of it
+------------------------
 
 That's OK, we all do.  You've probably been told by your long-time Unix
 user helper that ``GNU emacs`` automatically formats the C sources for
@@ -728,8 +728,8 @@ set automatically if you are using an editor that is compatible with
 EditorConfig. See the official EditorConfig website for more information:
 https://editorconfig.org/
 
-10) Kconfig configuration files
--------------------------------
+Kconfig configuration files
+---------------------------
 
 For all of the Kconfig* configuration files throughout the source tree,
 the indentation is somewhat different.  Lines under a ``config`` definition
@@ -757,8 +757,8 @@ For full documentation on the configuration files, see the file
 Documentation/kbuild/kconfig-language.rst.
 
 
-11) Data structures
--------------------
+Data structures
+---------------
 
 Data structures that have visibility outside the single-threaded
 environment they are created and destroyed in should always have
@@ -789,8 +789,8 @@ Remember: if another thread can find your data structure, and you don't
 have a reference count on it, you almost certainly have a bug.
 
 
-12) Macros, Enums and RTL
--------------------------
+Macros, Enums and RTL
+---------------------
 
 Names of macros defining constants and labels in enums are capitalized.
 
@@ -893,8 +893,8 @@ The cpp manual deals with macros exhaustively. The gcc internals manual also
 covers RTL which is used frequently with assembly language in the kernel.
 
 
-13) Printing kernel messages
-----------------------------
+Printing kernel messages
+------------------------
 
 Kernel developers like to be seen as literate. Do mind the spelling
 of kernel messages to make a good impression. Do not use incorrect
@@ -929,8 +929,8 @@ already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be
 used.
 
 
-14) Allocating memory
----------------------
+Allocating memory
+-----------------
 
 The kernel provides the following general purpose memory allocators:
 kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and
@@ -971,8 +971,8 @@ These generic allocation functions all emit a stack dump on failure when used
 without __GFP_NOWARN so there is no use in emitting an additional failure
 message when NULL is returned.
 
-15) The inline disease
-----------------------
+The inline disease
+------------------
 
 There appears to be a common misperception that gcc has a magic "make me
 faster" speedup option called ``inline``. While the use of inlines can be
@@ -999,8 +999,8 @@ appears outweighs the potential value of the hint that tells gcc to do
 something it would have done anyway.
 
 
-16) Function return values and names
-------------------------------------
+Function return values and names
+--------------------------------
 
 Functions can return values of many different kinds, and one of the
 most common is a value indicating whether the function succeeded or
@@ -1034,8 +1034,8 @@ result.  Typical examples would be functions that return pointers; they use
 NULL or the ERR_PTR mechanism to report failure.
 
 
-17) Using bool
---------------
+Using bool
+----------
 
 The Linux kernel bool type is an alias for the C99 _Bool type. bool values can
 only evaluate to 0 or 1, and implicit or explicit conversion to bool
@@ -1064,8 +1064,8 @@ readable alternative if the call-sites have naked true/false constants.
 Otherwise limited use of bool in structures and arguments can improve
 readability.
 
-18) Don't re-invent the kernel macros
--------------------------------------
+Don't re-invent the kernel macros
+---------------------------------
 
 The header file include/linux/kernel.h contains a number of macros that
 you should use, rather than explicitly coding some variant of them yourself.
@@ -1087,8 +1087,8 @@ need them.  Feel free to peruse that header file to see what else is already
 defined that you shouldn't reproduce in your code.
 
 
-19) Editor modelines and other cruft
-------------------------------------
+Editor modelines and other cruft
+--------------------------------
 
 Some editors can interpret configuration information embedded in source files,
 indicated with special markers.  For example, emacs interprets lines marked
@@ -1121,8 +1121,8 @@ own custom mode, or may have some other magic method for making indentation
 work correctly.
 
 
-20) Inline assembly
--------------------
+Inline assembly
+---------------
 
 In architecture-specific code, you may need to use inline assembly to interface
 with CPU or platform functionality.  Don't hesitate to do so when necessary.
@@ -1153,8 +1153,8 @@ the next instruction in the assembly output:
 	     : /* outputs */ : /* inputs */ : /* clobbers */);
 
 
-21) Conditional Compilation
----------------------------
+Conditional Compilation
+-----------------------
 
 Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c
 files; doing so makes code harder to read and logic harder to follow.  Instead,
@@ -1202,8 +1202,8 @@ expression used.  For instance:
 	#endif /* CONFIG_SOMETHING */
 
 
-22) Do not crash the kernel
----------------------------
+Do not crash the kernel
+-----------------------
 
 In general, the decision to crash the kernel belongs to the user, rather
 than to the kernel developer.
@@ -1264,8 +1264,8 @@ Use BUILD_BUG_ON() for compile-time assertions
 The use of BUILD_BUG_ON() is acceptable and encouraged, because it is a
 compile-time assertion that has no effect at runtime.
 
-Appendix I) References
-----------------------
+References
+----------
 
 The C Programming Language, Second Edition
 by Brian W. Kernighan and Dennis M. Ritchie.
-- 
2.49.0

Powered by blists - more mailing lists