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: split out the special-section state

Browse Source 
The state known as BODY_WITH_BLANK_LINE really, in a convoluted way,
indicates a "special section" that is terminated by a blank line or the
beginning of a new section.  That is either "@param: desc" sections, or the
weird "context" section that plays by the same rules.

Rename the state to SPECIAL_SECTION and split its processing into a
separate function; no real changes to the logic yet.

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-5-corbet@lwn.net
This commit is contained in:
Jonathan Corbet
2025-06-21 14:35:07 -06:00
parent e4153a2255
commit 74cee0dfc2
1 changed files with 12 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -88,7 +88,7 @@ class state:
NAME = 1 # looking for function name
DECLARATION = 2 # We have seen a declaration which might not be done
BODY = 3 # the body of the comment
BODY_WITH_BLANK_LINE = 4 # the body which has a blank line
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
@@ -98,7 +98,7 @@ class state:
"NAME",
"DECLARATION",
"BODY",
"BODY_WITH_BLANK_LINE",
"SPECIAL_SECTION",
"PROTO",
"DOCBLOCK",
"INLINE",
@@ -1383,18 +1383,18 @@ class KernelDoc:
self.emit_msg(ln, f"bad line: {line}")
def process_special(self, ln, line):
"""
STATE_SPECIAL_SECTION: a section ending with a blank line
"""
if KernRe(r"\s*\*\s*\S").match(line):
self.entry.begin_section(ln, dump = True)
self.process_body(ln, line)
def process_body(self, ln, line):
"""
STATE_BODY: the bulk of a kerneldoc comment.
"""
if self.state == state.BODY_WITH_BLANK_LINE:
r = KernRe(r"\s*\*\s*\S")
if r.match(line):
self.dump_section()
self.entry.begin_section(ln)
self.entry.contents = ""
if doc_sect.search(line):
self.entry.in_doc_sect = True
newsection = doc_sect.group(1)
@@ -1452,7 +1452,7 @@ class KernelDoc:
self.state = state.BODY
else:
if self.entry.section != SECTION_DEFAULT:
self.state = state.BODY_WITH_BLANK_LINE
self.state = state.SPECIAL_SECTION
else:
self.state = state.BODY
@@ -1751,7 +1751,7 @@ class KernelDoc:
state.NAME: process_name,
state.BODY: process_body,
state.DECLARATION: process_decl,
state.BODY_WITH_BLANK_LINE: process_body,
state.SPECIAL_SECTION: process_special,
state.INLINE: process_inline,
state.PROTO: process_proto,
state.DOCBLOCK: process_docblock,