raspi/linux
1
0
Fork 1
mirror of https://github.com/raspberrypi/linux.git synced 2025-12-15 22:41:38 +00:00
Code Issues Projects Releases Wiki Activity

docs: kdoc: Move content handling into KernelEntry

Browse Source 
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@lwn.net>
This commit is contained in:
Jonathan Corbet
2025-06-25 14:51:11 -06:00
parent d982828d08
commit d6699d5f60
1 changed files with 30 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
scripts/lib/kdoc/kdoc_parser.py
View File

@@ -128,7 +128,7 @@ class KernelEntry:
def __init__(self, config, ln): def __init__(self, config, ln):
self.config = config self.config = config
self.contents = "" self._contents = []
self.function = "" self.function = ""
self.sectcheck = "" self.sectcheck = ""
self.struct_actual = "" self.struct_actual = ""
@@ -153,6 +153,15 @@ class KernelEntry:
self.brcount = 0 self.brcount = 0
self.declaration_start_line = ln + 1 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 # TODO: rename to emit_message after removal of kernel-doc.pl
def emit_msg(self, log_msg, warning=True): def emit_msg(self, log_msg, warning=True):
"""Emit a message""" """Emit a message"""
@@ -180,9 +189,14 @@ class KernelEntry:
""" """
Dumps section contents to arrays/hashes intended for that purpose. 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 name = self.section
contents = self.contents contents = self.contents()
if type_param.match(name): if type_param.match(name):
name = type_param.group(1) name = type_param.group(1)
@@ -206,7 +220,8 @@ class KernelEntry:
if name != SECTION_DEFAULT: if name != SECTION_DEFAULT:
self.emit_msg(self.new_start_line, self.emit_msg(self.new_start_line,
f"duplicate section name '{name}'\n") 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: else:
self.sections[name] = contents self.sections[name] = contents
self.sectionlist.append(name) self.sectionlist.append(name)
@@ -217,7 +232,7 @@ class KernelEntry:
if start_new: if start_new:
self.section = SECTION_DEFAULT self.section = SECTION_DEFAULT
self.contents = "" self._contents = []
class KernelDoc: class KernelDoc:
@@ -1334,16 +1349,11 @@ class KernelDoc:
newcontents = doc_sect.group(2) newcontents = doc_sect.group(2)
if not newcontents: if not newcontents:
newcontents = "" newcontents = ""
self.dump_section()
if self.entry.contents.strip("\n"):
self.dump_section()
self.entry.begin_section(ln, newsection) self.entry.begin_section(ln, newsection)
self.entry.leading_space = None self.entry.leading_space = None
self.entry.contents = newcontents.lstrip() self.entry.add_text(newcontents.lstrip())
if self.entry.contents:
self.entry.contents += "\n"
return True return True
return False return False
@@ -1385,7 +1395,6 @@ class KernelDoc:
# #
if cont == "": if cont == "":
self.state = state.BODY self.state = state.BODY
self.entry.contents += "\n" # needed?
# #
# Otherwise we have more of the declaration section to soak up. # Otherwise we have more of the declaration section to soak up.
# #
@@ -1407,7 +1416,6 @@ class KernelDoc:
# #
if KernRe(r"\s*\*\s*$").match(line): if KernRe(r"\s*\*\s*$").match(line):
self.entry.begin_section(ln, dump = True) self.entry.begin_section(ln, dump = True)
self.entry.contents += '\n'
self.state = state.BODY self.state = state.BODY
return return
# #
@@ -1444,7 +1452,7 @@ class KernelDoc:
# #
# Add the trimmed result to the section and we're done. # 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: else:
# Unknown line, ignore # Unknown line, ignore
self.emit_msg(ln, f"bad line: {line}") self.emit_msg(ln, f"bad line: {line}")
@@ -1458,7 +1466,7 @@ class KernelDoc:
if doc_content.search(line): if doc_content.search(line):
cont = doc_content.group(1) cont = doc_content.group(1)
self.entry.contents += cont + "\n" self.entry.add_text(cont)
else: else:
# Unknown line, ignore # Unknown line, ignore
self.emit_msg(ln, f"bad line: {line}") self.emit_msg(ln, f"bad line: {line}")
@@ -1470,27 +1478,20 @@ class KernelDoc:
doc_inline_sect.search(line): doc_inline_sect.search(line):
self.entry.begin_section(ln, doc_inline_sect.group(1)) self.entry.begin_section(ln, doc_inline_sect.group(1))
self.entry.contents = doc_inline_sect.group(2).lstrip() self.entry.add_text(doc_inline_sect.group(2).lstrip())
if self.entry.contents != "":
self.entry.contents += "\n"
self.inline_doc_state = state.INLINE_TEXT self.inline_doc_state = state.INLINE_TEXT
# Documentation block end */ # Documentation block end */
return return
if doc_inline_end.search(line): if doc_inline_end.search(line):
if self.entry.contents not in ["", "\n"]: self.dump_section()
self.dump_section()
self.state = state.PROTO self.state = state.PROTO
self.inline_doc_state = state.INLINE_NA self.inline_doc_state = state.INLINE_NA
return return
if doc_content.search(line): if doc_content.search(line):
if self.inline_doc_state == state.INLINE_TEXT: if self.inline_doc_state == state.INLINE_TEXT:
self.entry.contents += doc_content.group(1) + "\n" self.entry.add_text(doc_content.group(1))
if not self.entry.contents.strip(" ").rstrip("\n"):
self.entry.contents = ""
elif self.inline_doc_state == state.INLINE_NAME: elif self.inline_doc_state == state.INLINE_NAME:
self.emit_msg(ln, self.emit_msg(ln,
@@ -1668,11 +1669,8 @@ class KernelDoc:
if doc_inline_oneline.search(line): if doc_inline_oneline.search(line):
self.entry.begin_section(ln, doc_inline_oneline.group(1)) self.entry.begin_section(ln, doc_inline_oneline.group(1))
self.entry.contents = doc_inline_oneline.group(2) self.entry.add_text(doc_inline_oneline.group(2))
self.dump_section()
if self.entry.contents != "":
self.entry.contents += "\n"
self.dump_section(start_new=False)
elif doc_inline_start.search(line): elif doc_inline_start.search(line):
self.state = state.INLINE self.state = state.INLINE
@@ -1696,7 +1694,7 @@ class KernelDoc:
self.reset_state(ln) self.reset_state(ln)
elif doc_content.search(line): 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): def parse_export(self):
""" """