Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: kdoc: split out the special-section state
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
+12
-12
+12
-12
scripts/lib/kdoc/kdoc_parser.py
+12
-12
scripts/lib/kdoc/kdoc_parser.py
···
88
88
NAME = 1 # looking for function name
89
89
DECLARATION = 2 # We have seen a declaration which might not be done
90
90
BODY = 3 # the body of the comment
91
-
BODY_WITH_BLANK_LINE = 4 # the body which has a blank line
91
+
SPECIAL_SECTION = 4 # doc section ending with a blank line
92
92
PROTO = 5 # scanning prototype
93
93
DOCBLOCK = 6 # documentation block
94
94
INLINE = 7 # gathering doc outside main block
···
98
98
"NAME",
99
99
"DECLARATION",
100
100
"BODY",
101
-
"BODY_WITH_BLANK_LINE",
101
+
"SPECIAL_SECTION",
102
102
"PROTO",
103
103
"DOCBLOCK",
104
104
"INLINE",
···
1383
1383
self.emit_msg(ln, f"bad line: {line}")
1384
1384
1385
1385
1386
+
def process_special(self, ln, line):
1387
+
"""
1388
+
STATE_SPECIAL_SECTION: a section ending with a blank line
1389
+
"""
1390
+
if KernRe(r"\s*\*\s*\S").match(line):
1391
+
self.entry.begin_section(ln, dump = True)
1392
+
self.process_body(ln, line)
1393
+
1386
1394
def process_body(self, ln, line):
1387
1395
"""
1388
1396
STATE_BODY: the bulk of a kerneldoc comment.
1389
1397
"""
1390
-
1391
-
if self.state == state.BODY_WITH_BLANK_LINE:
1392
-
r = KernRe(r"\s*\*\s*\S")
1393
-
if r.match(line):
1394
-
self.dump_section()
1395
-
self.entry.begin_section(ln)
1396
-
self.entry.contents = ""
1397
-
1398
1398
if doc_sect.search(line):
1399
1399
self.entry.in_doc_sect = True
1400
1400
newsection = doc_sect.group(1)
···
1452
1452
self.state = state.BODY
1453
1453
else:
1454
1454
if self.entry.section != SECTION_DEFAULT:
1455
-
self.state = state.BODY_WITH_BLANK_LINE
1455
+
self.state = state.SPECIAL_SECTION
1456
1456
else:
1457
1457
self.state = state.BODY
1458
1458
···
1751
1751
state.NAME: process_name,
1752
1752
state.BODY: process_body,
1753
1753
state.DECLARATION: process_decl,
1754
-
state.BODY_WITH_BLANK_LINE: process_body,
1754
+
state.SPECIAL_SECTION: process_special,
1755
1755
state.INLINE: process_inline,
1756
1756
state.PROTO: process_proto,
1757
1757
state.DOCBLOCK: process_docblock,