Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: kdoc: separate out the handling of the declaration phase
The BODY_MAYBE state really describes the "we are in a declaration" state.
Rename it accordingly, and split the handling of this state out from that
of the other BODY* states. This change introduces a fair amount of
duplicated code that will be coalesced in a later patch.
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-4-corbet@lwn.net
+78
-15
+78
-15
scripts/lib/kdoc/kdoc_parser.py
+78
-15
scripts/lib/kdoc/kdoc_parser.py
···
86
86
# Parser states
87
87
NORMAL = 0 # normal code
88
88
NAME = 1 # looking for function name
89
-
BODY_MAYBE = 2 # body - or maybe more description
89
+
DECLARATION = 2 # We have seen a declaration which might not be done
90
90
BODY = 3 # the body of the comment
91
91
BODY_WITH_BLANK_LINE = 4 # the body which has a blank line
92
92
PROTO = 5 # scanning prototype
···
96
96
name = [
97
97
"NORMAL",
98
98
"NAME",
99
-
"BODY_MAYBE",
99
+
"DECLARATION",
100
100
"BODY",
101
101
"BODY_WITH_BLANK_LINE",
102
102
"PROTO",
···
1287
1287
r = KernRe("[-:](.*)")
1288
1288
if r.search(line):
1289
1289
self.entry.declaration_purpose = trim_whitespace(r.group(1))
1290
-
self.state = state.BODY_MAYBE
1290
+
self.state = state.DECLARATION
1291
1291
else:
1292
1292
self.entry.declaration_purpose = ""
1293
1293
···
1310
1310
else:
1311
1311
self.emit_msg(ln, f"Cannot find identifier on line:\n{line}")
1312
1312
1313
+
def process_decl(self, ln, line):
1314
+
"""
1315
+
STATE_DECLARATION: We've seen the beginning of a declaration
1316
+
"""
1317
+
if doc_sect.search(line):
1318
+
self.entry.in_doc_sect = True
1319
+
newsection = doc_sect.group(1)
1320
+
1321
+
if newsection.lower() in ["description", "context"]:
1322
+
newsection = newsection.title()
1323
+
1324
+
# Special case: @return is a section, not a param description
1325
+
if newsection.lower() in ["@return", "@returns",
1326
+
"return", "returns"]:
1327
+
newsection = "Return"
1328
+
1329
+
# Perl kernel-doc has a check here for contents before sections.
1330
+
# the logic there is always false, as in_doc_sect variable is
1331
+
# always true. So, just don't implement Wcontents_before_sections
1332
+
1333
+
# .title()
1334
+
newcontents = doc_sect.group(2)
1335
+
if not newcontents:
1336
+
newcontents = ""
1337
+
1338
+
if self.entry.contents.strip("\n"):
1339
+
self.dump_section()
1340
+
1341
+
self.entry.begin_section(ln, newsection)
1342
+
self.entry.leading_space = None
1343
+
1344
+
self.entry.contents = newcontents.lstrip()
1345
+
if self.entry.contents:
1346
+
self.entry.contents += "\n"
1347
+
1348
+
self.state = state.BODY
1349
+
return
1350
+
1351
+
if doc_end.search(line):
1352
+
self.dump_section()
1353
+
1354
+
# Look for doc_com + <text> + doc_end:
1355
+
r = KernRe(r'\s*\*\s*[a-zA-Z_0-9:\.]+\*/')
1356
+
if r.match(line):
1357
+
self.emit_msg(ln, f"suspicious ending line: {line}")
1358
+
1359
+
self.entry.prototype = ""
1360
+
self.entry.new_start_line = ln + 1
1361
+
1362
+
self.state = state.PROTO
1363
+
return
1364
+
1365
+
if doc_content.search(line):
1366
+
cont = doc_content.group(1)
1367
+
1368
+
if cont == "":
1369
+
self.state = state.BODY
1370
+
self.entry.contents += "\n" # needed?
1371
+
1372
+
else:
1373
+
# Continued declaration purpose
1374
+
self.entry.declaration_purpose = self.entry.declaration_purpose.rstrip()
1375
+
self.entry.declaration_purpose += " " + cont
1376
+
1377
+
r = KernRe(r"\s+")
1378
+
self.entry.declaration_purpose = r.sub(' ',
1379
+
self.entry.declaration_purpose)
1380
+
return
1381
+
1382
+
# Unknown line, ignore
1383
+
self.emit_msg(ln, f"bad line: {line}")
1384
+
1385
+
1313
1386
def process_body(self, ln, line):
1314
1387
"""
1315
-
STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment.
1388
+
STATE_BODY: the bulk of a kerneldoc comment.
1316
1389
"""
1317
1390
1318
1391
if self.state == state.BODY_WITH_BLANK_LINE:
···
1457
1384
self.state = state.BODY
1458
1385
1459
1386
self.entry.contents += "\n"
1460
-
1461
-
elif self.state == state.BODY_MAYBE:
1462
-
1463
-
# Continued declaration purpose
1464
-
self.entry.declaration_purpose = self.entry.declaration_purpose.rstrip()
1465
-
self.entry.declaration_purpose += " " + cont
1466
-
1467
-
r = KernRe(r"\s+")
1468
-
self.entry.declaration_purpose = r.sub(' ',
1469
-
self.entry.declaration_purpose)
1470
1387
1471
1388
else:
1472
1389
if self.entry.section.startswith('@') or \
···
1750
1687
state.NORMAL: process_normal,
1751
1688
state.NAME: process_name,
1752
1689
state.BODY: process_body,
1753
-
state.BODY_MAYBE: process_body,
1690
+
state.DECLARATION: process_decl,
1754
1691
state.BODY_WITH_BLANK_LINE: process_body,
1755
1692
state.INLINE: process_inline,
1756
1693
state.PROTO: process_proto,