linux-kernel - [PATCH 7/8] docs: kdoc: remove the inline states-within-a-state

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <20250627184000.132291-8-corbet@lwn.net>
Date: Fri, 27 Jun 2025 12:39:59 -0600
From: Jonathan Corbet <corbet@....net>
To: linux-doc@...r.kernel.org
Cc: linux-kernel@...r.kernel.org,
	Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
	Akira Yokosawa <akiyks@...il.com>,
	Jonathan Corbet <corbet@....net>
Subject: [PATCH 7/8] docs: kdoc: remove the inline states-within-a-state

The processing of inline kerneldoc comments is a state like the rest, but
it was implemented as a set of separate substates.  Just remove the
substate logic and make the inline states normal ones like the rest.

INLINE_ERROR was never actually used for anything, so just take it out.

No changes to the generated output.

Signed-off-by: Jonathan Corbet <corbet@....net>
---
 scripts/lib/kdoc/kdoc_parser.py | 43 ++++++++++-----------------------
 1 file changed, 13 insertions(+), 30 deletions(-)

diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
index 03a0e44707a7..a931c1471fa8 100644
--- a/scripts/lib/kdoc/kdoc_parser.py
+++ b/scripts/lib/kdoc/kdoc_parser.py
@@ -91,7 +91,8 @@ class state:
     SPECIAL_SECTION = 4      # doc section ending with a blank line
     PROTO         = 5        # scanning prototype
     DOCBLOCK      = 6        # documentation block
-    INLINE        = 7        # gathering doc outside main block
+    INLINE_NAME   = 7        # gathering doc outside main block
+    INLINE_TEXT   = 8	     # reading the body of inline docs
 
     name = [
         "NORMAL",
@@ -101,23 +102,10 @@ class state:
         "SPECIAL_SECTION",
         "PROTO",
         "DOCBLOCK",
-        "INLINE",
+        "INLINE_NAME",
+        "INLINE_TEXT",
     ]
 
-    # Inline documentation state
-    INLINE_NA     = 0 # not applicable ($state != INLINE)
-    INLINE_NAME   = 1 # looking for member name (@foo:)
-    INLINE_TEXT   = 2 # looking for member documentation
-    INLINE_ERROR  = 3 # error - Comment without header was found.
-                      # Spit a warning as it's not
-                      # proper kernel-doc and ignore the rest.
-
-    inline_name = [
-        "",
-        "_NAME",
-        "_TEXT",
-        "_ERROR",
-    ]
 
 SECTION_DEFAULT = "Description"  # default section
 
@@ -246,7 +234,6 @@ class KernelDoc:
 
         # Initial state for the state machines
         self.state = state.NORMAL
-        self.inline_doc_state = state.INLINE_NA
 
         # Store entry currently being processed
         self.entry = None
@@ -323,7 +310,6 @@ class KernelDoc:
 
         # State flags
         self.state = state.NORMAL
-        self.inline_doc_state = state.INLINE_NA
 
     def push_parameter(self, ln, decl_type, param, dtype,
                        org_arg, declaration_name):
@@ -1465,30 +1451,28 @@ class KernelDoc:
     def process_inline(self, ln, line):
         """STATE_INLINE: docbook comments within a prototype."""
 
-        if self.inline_doc_state == state.INLINE_NAME and \
+        if self.state == state.INLINE_NAME and \
            doc_inline_sect.search(line):
             self.entry.begin_section(ln, doc_inline_sect.group(1))
 
             self.entry.add_text(doc_inline_sect.group(2).lstrip())
-            self.inline_doc_state = state.INLINE_TEXT
+            self.state = state.INLINE_TEXT
             # Documentation block end */
             return
 
         if doc_inline_end.search(line):
             self.dump_section()
             self.state = state.PROTO
-            self.inline_doc_state = state.INLINE_NA
             return
 
         if doc_content.search(line):
-            if self.inline_doc_state == state.INLINE_TEXT:
+            if self.state == state.INLINE_TEXT:
                 self.entry.add_text(doc_content.group(1))
 
-            elif self.inline_doc_state == state.INLINE_NAME:
+            elif self.state == state.INLINE_NAME:
                 self.emit_msg(ln,
                               f"Incorrect use of kernel-doc format: {line}")
-
-                self.inline_doc_state = state.INLINE_ERROR
+                self.state = state.PROTO
 
     def syscall_munge(self, ln, proto):         # pylint: disable=W0613
         """
@@ -1664,8 +1648,7 @@ class KernelDoc:
             self.dump_section()
 
         elif doc_inline_start.search(line):
-            self.state = state.INLINE
-            self.inline_doc_state = state.INLINE_NAME
+            self.state = state.INLINE_NAME
 
         elif self.entry.decl_type == 'function':
             self.process_proto_function(ln, line)
@@ -1716,7 +1699,8 @@ class KernelDoc:
         state.BODY:			process_body,
         state.DECLARATION:		process_decl,
         state.SPECIAL_SECTION:		process_special,
-        state.INLINE:			process_inline,
+        state.INLINE_NAME:		process_inline,
+        state.INLINE_TEXT:		process_inline,
         state.PROTO:			process_proto,
         state.DOCBLOCK:			process_docblock,
         }
@@ -1756,9 +1740,8 @@ class KernelDoc:
                             prev = ""
                             prev_ln = None
 
-                    self.config.log.debug("%d %s%s: %s",
+                    self.config.log.debug("%d %s: %s",
                                           ln, state.name[self.state],
-                                          state.inline_name[self.inline_doc_state],
                                           line)
 
                     # This is an optimization over the original script.
-- 
2.49.0