admin/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux.git synced 2025-12-07 20:06:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: kdoc: finish disentangling the BODY and SPECIAL_SECTION states

Browse Source 
Move the last SPECIAL_SECTION special case into the proper handler
function, getting rid of more if/then/else logic.  The leading-space
tracking was tightened up a bit in the move.  Add some comments describing
what is going on.

No changes to the generated output.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250621203512.223189-10-corbet@lwn.net
This commit is contained in:
Jonathan Corbet
2025-06-21 14:35:12 -06:00
parent ccad65a494
commit 07e04d8e7d
1 changed files with 48 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1405,10 +1405,53 @@ class KernelDoc:
"""
STATE_SPECIAL_SECTION: a section ending with a blank line
"""
#
# If we have hit a blank line (only the " * " marker), then this
# section is done.
#
if KernRe(r"\s*\*\s*$").match(line):
self.entry.begin_section(ln, dump = True)
self.entry.contents += '\n'
self.state = state.BODY
self.process_body(ln, line)
return
#
# Not a blank line, look for the other ways to end the section.
#
if self.is_new_section(ln, line) or self.is_comment_end(ln, line):
return
#
# OK, we should have a continuation of the text for this section.
#
if doc_content.search(line):
cont = doc_content.group(1)
#
# If the lines of text after the first in a special section have
# leading white space, we need to trim it out or Sphinx will get
# confused. For the second line (the None case), see what we
# find there and remember it.
#
if self.entry.leading_space is None:
r = KernRe(r'^(\s+)')
if r.match(cont):
self.entry.leading_space = len(r.group(1))
else:
self.entry.leading_space = 0
#
# Otherwise, before trimming any leading chars, be *sure*
# that they are white space. We should maybe warn if this
# isn't the case.
#
for i in range(0, self.entry.leading_space):
if cont[i] != " ":
self.entry.leading_space = i
break
#
# Add the trimmed result to the section and we're done.
#
self.entry.contents += cont[self.entry.leading_space:] + '\n'
else:
# Unknown line, ignore
self.emit_msg(ln, f"bad line: {line}")
def process_body(self, ln, line):
"""
@@ -1419,37 +1462,10 @@ class KernelDoc:
if doc_content.search(line):
cont = doc_content.group(1)
if cont == "":
self.entry.contents += "\n"
else:
if self.state == state.SPECIAL_SECTION:
if self.entry.leading_space is None:
r = KernRe(r'^(\s+)')
if r.match(cont):
self.entry.leading_space = len(r.group(1))
else:
self.entry.leading_space = 0
# Double-check if leading space are realy spaces
pos = 0
for i in range(0, self.entry.leading_space):
if cont[i] != " ":
break
pos += 1
cont = cont[pos:]
# NEW LOGIC:
# In case it is different, update it
if self.entry.leading_space != pos:
self.entry.leading_space = pos
self.entry.contents += cont + "\n"
return
# Unknown line, ignore
self.emit_msg(ln, f"bad line: {line}")
self.entry.contents += cont + "\n"
else:
# Unknown line, ignore
self.emit_msg(ln, f"bad line: {line}")
def process_inline(self, ln, line):
"""STATE_INLINE: docbook comments within a prototype."""