| 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
| ||
|
Message-ID: <20250627184000.132291-3-corbet@lwn.net>
Date: Fri, 27 Jun 2025 12:39:54 -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/8] docs: kdoc: Move content handling into KernelEntry
Rather than having other code mucking around with this bit of internal
state, encapsulate it internally. Accumulate the description as a list of
strings, joining them at the end, which is a more efficient way of building
the text.
Signed-off-by: Jonathan Corbet <corbet@....net>
---
scripts/lib/kdoc/kdoc_parser.py | 62 ++++++++++++++++-----------------
1 file changed, 30 insertions(+), 32 deletions(-)
diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
index f3970ffbf402..f87355b63c19 100644
--- a/scripts/lib/kdoc/kdoc_parser.py
+++ b/scripts/lib/kdoc/kdoc_parser.py
@@ -128,7 +128,7 @@ class KernelEntry:
def __init__(self, config, ln):
self.config = config
- self.contents = ""
+ self._contents = []
self.function = ""
self.sectcheck = ""
self.struct_actual = ""
@@ -153,6 +153,15 @@ class KernelEntry:
self.brcount = 0
self.declaration_start_line = ln + 1
+ #
+ # Management of section contents
+ #
+ def add_text(self, text):
+ self._contents.append(text)
+
+ def contents(self):
+ return '\n'.join(self._contents) + '\n'
+
# TODO: rename to emit_message after removal of kernel-doc.pl
def emit_msg(self, log_msg, warning=True):
"""Emit a message"""
@@ -180,9 +189,14 @@ class KernelEntry:
"""
Dumps section contents to arrays/hashes intended for that purpose.
"""
-
+ #
+ # If we have accumulated no contents in the default ("description")
+ # section, don't bother.
+ #
+ if self.section == SECTION_DEFAULT and not self._contents:
+ return
name = self.section
- contents = self.contents
+ contents = self.contents()
if type_param.match(name):
name = type_param.group(1)
@@ -206,7 +220,8 @@ class KernelEntry:
if name != SECTION_DEFAULT:
self.emit_msg(self.new_start_line,
f"duplicate section name '{name}'\n")
- self.sections[name] += contents
+ # Treat as a new paragraph - add a blank line
+ self.sections[name] += '\n' + contents
else:
self.sections[name] = contents
self.sectionlist.append(name)
@@ -217,7 +232,7 @@ class KernelEntry:
if start_new:
self.section = SECTION_DEFAULT
- self.contents = ""
+ self._contents = []
class KernelDoc:
@@ -1334,16 +1349,11 @@ class KernelDoc:
newcontents = doc_sect.group(2)
if not newcontents:
newcontents = ""
-
- if self.entry.contents.strip("\n"):
- self.dump_section()
-
+ self.dump_section()
self.entry.begin_section(ln, newsection)
self.entry.leading_space = None
- self.entry.contents = newcontents.lstrip()
- if self.entry.contents:
- self.entry.contents += "\n"
+ self.entry.add_text(newcontents.lstrip())
return True
return False
@@ -1385,7 +1395,6 @@ class KernelDoc:
#
if cont == "":
self.state = state.BODY
- self.entry.contents += "\n" # needed?
#
# Otherwise we have more of the declaration section to soak up.
#
@@ -1407,7 +1416,6 @@ class KernelDoc:
#
if KernRe(r"\s*\*\s*$").match(line):
self.entry.begin_section(ln, dump = True)
- self.entry.contents += '\n'
self.state = state.BODY
return
#
@@ -1444,7 +1452,7 @@ class KernelDoc:
#
# Add the trimmed result to the section and we're done.
#
- self.entry.contents += cont[self.entry.leading_space:] + '\n'
+ self.entry.add_text(cont[self.entry.leading_space:])
else:
# Unknown line, ignore
self.emit_msg(ln, f"bad line: {line}")
@@ -1458,7 +1466,7 @@ class KernelDoc:
if doc_content.search(line):
cont = doc_content.group(1)
- self.entry.contents += cont + "\n"
+ self.entry.add_text(cont)
else:
# Unknown line, ignore
self.emit_msg(ln, f"bad line: {line}")
@@ -1470,27 +1478,20 @@ class KernelDoc:
doc_inline_sect.search(line):
self.entry.begin_section(ln, doc_inline_sect.group(1))
- self.entry.contents = doc_inline_sect.group(2).lstrip()
- if self.entry.contents != "":
- self.entry.contents += "\n"
-
+ self.entry.add_text(doc_inline_sect.group(2).lstrip())
self.inline_doc_state = state.INLINE_TEXT
# Documentation block end */
return
if doc_inline_end.search(line):
- if self.entry.contents not in ["", "\n"]:
- self.dump_section()
-
+ 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:
- self.entry.contents += doc_content.group(1) + "\n"
- if not self.entry.contents.strip(" ").rstrip("\n"):
- self.entry.contents = ""
+ self.entry.add_text(doc_content.group(1))
elif self.inline_doc_state == state.INLINE_NAME:
self.emit_msg(ln,
@@ -1668,11 +1669,8 @@ class KernelDoc:
if doc_inline_oneline.search(line):
self.entry.begin_section(ln, doc_inline_oneline.group(1))
- self.entry.contents = doc_inline_oneline.group(2)
-
- if self.entry.contents != "":
- self.entry.contents += "\n"
- self.dump_section(start_new=False)
+ self.entry.add_text(doc_inline_oneline.group(2))
+ self.dump_section()
elif doc_inline_start.search(line):
self.state = state.INLINE
@@ -1696,7 +1694,7 @@ class KernelDoc:
self.reset_state(ln)
elif doc_content.search(line):
- self.entry.contents += doc_content.group(1) + "\n"
+ self.entry.add_text(doc_content.group(1))
def parse_export(self):
"""
--
2.49.0
Powered by blists - more mailing lists