Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: kdoc: Add some comments to process_decl()
Now that the function can actually fit into a human brain, add a few
comments. While I was at it, I switched to the trim_whitespace() helper
rather than open-coding it.
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-9-corbet@lwn.net
+16
-14
+16
-14
scripts/lib/kdoc/kdoc_parser.py
+16
-14
scripts/lib/kdoc/kdoc_parser.py
···
1377
1377
"""
1378
1378
if self.is_new_section(ln, line) or self.is_comment_end(ln, line):
1379
1379
return
1380
-
1380
+
#
1381
+
# Look for anything with the " * " line beginning.
1382
+
#
1381
1383
if doc_content.search(line):
1382
1384
cont = doc_content.group(1)
1383
-
1385
+
#
1386
+
# A blank line means that we have moved out of the declaration
1387
+
# part of the comment (without any "special section" parameter
1388
+
# descriptions).
1389
+
#
1384
1390
if cont == "":
1385
1391
self.state = state.BODY
1386
1392
self.entry.contents += "\n" # needed?
1387
-
1393
+
#
1394
+
# Otherwise we have more of the declaration section to soak up.
1395
+
#
1388
1396
else:
1389
-
# Continued declaration purpose
1390
-
self.entry.declaration_purpose = self.entry.declaration_purpose.rstrip()
1391
-
self.entry.declaration_purpose += " " + cont
1392
-
1393
-
r = KernRe(r"\s+")
1394
-
self.entry.declaration_purpose = r.sub(' ',
1395
-
self.entry.declaration_purpose)
1396
-
return
1397
-
1398
-
# Unknown line, ignore
1399
-
self.emit_msg(ln, f"bad line: {line}")
1397
+
self.entry.declaration_purpose = \
1398
+
trim_whitespace(self.entry.declaration_purpose + ' ' + cont)
1399
+
else:
1400
+
# Unknown line, ignore
1401
+
self.emit_msg(ln, f"bad line: {line}")
1400
1402
1401
1403
1402
1404
def process_special(self, ln, line):