linux-kernel - [PATCH 2/9] docs: kdoc: consolidate the "begin section" logic

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: <20250621203512.223189-3-corbet@lwn.net>
Date: Sat, 21 Jun 2025 14:35:05 -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 2/9] docs: kdoc: consolidate the "begin section" logic

Pull the repeated "begin a section" logic into a single place and hide it
within the KernelEntry class.

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

diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
index c46e1b6a7d4b..d29a61a06f6d 100644
--- a/scripts/lib/kdoc/kdoc_parser.py
+++ b/scripts/lib/kdoc/kdoc_parser.py
@@ -169,6 +169,15 @@ class KernelEntry:
         self.warnings.append(log_msg)
         return
 
+    #
+    # Begin a new section.
+    #
+    def begin_section(self, line_no, title = SECTION_DEFAULT, dump = False):
+        if dump:
+            self.dump_section(start_new = True)
+        self.section = title
+        self.new_start_line = line_no
+
     def dump_section(self, start_new=True):
         """
         Dumps section contents to arrays/hashes intended for that purpose.
@@ -1231,12 +1240,11 @@ class KernelDoc:
         # Check for a DOC: block and handle them specially.
         #
         if doc_block.search(line):
-            self.entry.new_start_line = ln
 
             if not doc_block.group(1):
-                self.entry.section = "Introduction"
+                self.entry.begin_section(ln, "Introduction")
             else:
-                self.entry.section = doc_block.group(1)
+                self.entry.begin_section(ln, doc_block.group(1))
 
             self.entry.identifier = self.entry.section
             self.state = state.DOCBLOCK
@@ -1270,8 +1278,7 @@ class KernelDoc:
             self.state = state.BODY
             self.entry.identifier = self.entry.identifier.strip(" ")
             # if there's no @param blocks need to set up default section here
-            self.entry.section = SECTION_DEFAULT
-            self.entry.new_start_line = ln + 1
+            self.entry.begin_section(ln + 1)
             #
             # Find the description portion, which *should* be there but
             # isn't always.
@@ -1312,8 +1319,7 @@ class KernelDoc:
             r = KernRe(r"\s*\*\s*\S")
             if r.match(line):
                 self.dump_section()
-                self.entry.section = SECTION_DEFAULT
-                self.entry.new_start_line = ln
+                self.entry.begin_section(ln)
                 self.entry.contents = ""
 
         if doc_sect.search(line):
@@ -1340,8 +1346,7 @@ class KernelDoc:
             if self.entry.contents.strip("\n"):
                 self.dump_section()
 
-            self.entry.new_start_line = ln
-            self.entry.section = newsection
+            self.entry.begin_section(ln, newsection)
             self.entry.leading_space = None
 
             self.entry.contents = newcontents.lstrip()
@@ -1370,9 +1375,7 @@ class KernelDoc:
 
             if cont == "":
                 if self.entry.section == self.section_context:
-                    self.dump_section()
-
-                    self.entry.new_start_line = ln
+                    self.entry.begin_section(ln, dump = True)
                     self.state = state.BODY
                 else:
                     if self.entry.section != SECTION_DEFAULT:
@@ -1427,8 +1430,7 @@ class KernelDoc:
 
         if self.inline_doc_state == state.INLINE_NAME and \
            doc_inline_sect.search(line):
-            self.entry.section = doc_inline_sect.group(1)
-            self.entry.new_start_line = ln
+            self.entry.begin_section(ln, doc_inline_sect.group(1))
 
             self.entry.contents = doc_inline_sect.group(2).lstrip()
             if self.entry.contents != "":
@@ -1627,7 +1629,7 @@ class KernelDoc:
         """STATE_PROTO: reading a function/whatever prototype."""
 
         if doc_inline_oneline.search(line):
-            self.entry.section = doc_inline_oneline.group(1)
+            self.entry.begin_section(ln, doc_inline_oneline.group(1))
             self.entry.contents = doc_inline_oneline.group(2)
 
             if self.entry.contents != "":
-- 
2.49.0