Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: kdoc: finish disentangling the BODY and SPECIAL_SECTION states
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
+48
-32
+48
-32
scripts/lib/kdoc/kdoc_parser.py
+48
-32
scripts/lib/kdoc/kdoc_parser.py
···
1405
1405
"""
1406
1406
STATE_SPECIAL_SECTION: a section ending with a blank line
1407
1407
"""
1408
+
#
1409
+
# If we have hit a blank line (only the " * " marker), then this
1410
+
# section is done.
1411
+
#
1408
1412
if KernRe(r"\s*\*\s*$").match(line):
1409
1413
self.entry.begin_section(ln, dump = True)
1414
+
self.entry.contents += '\n'
1410
1415
self.state = state.BODY
1411
-
self.process_body(ln, line)
1416
+
return
1417
+
#
1418
+
# Not a blank line, look for the other ways to end the section.
1419
+
#
1420
+
if self.is_new_section(ln, line) or self.is_comment_end(ln, line):
1421
+
return
1422
+
#
1423
+
# OK, we should have a continuation of the text for this section.
1424
+
#
1425
+
if doc_content.search(line):
1426
+
cont = doc_content.group(1)
1427
+
#
1428
+
# If the lines of text after the first in a special section have
1429
+
# leading white space, we need to trim it out or Sphinx will get
1430
+
# confused. For the second line (the None case), see what we
1431
+
# find there and remember it.
1432
+
#
1433
+
if self.entry.leading_space is None:
1434
+
r = KernRe(r'^(\s+)')
1435
+
if r.match(cont):
1436
+
self.entry.leading_space = len(r.group(1))
1437
+
else:
1438
+
self.entry.leading_space = 0
1439
+
#
1440
+
# Otherwise, before trimming any leading chars, be *sure*
1441
+
# that they are white space. We should maybe warn if this
1442
+
# isn't the case.
1443
+
#
1444
+
for i in range(0, self.entry.leading_space):
1445
+
if cont[i] != " ":
1446
+
self.entry.leading_space = i
1447
+
break
1448
+
#
1449
+
# Add the trimmed result to the section and we're done.
1450
+
#
1451
+
self.entry.contents += cont[self.entry.leading_space:] + '\n'
1452
+
else:
1453
+
# Unknown line, ignore
1454
+
self.emit_msg(ln, f"bad line: {line}")
1412
1455
1413
1456
def process_body(self, ln, line):
1414
1457
"""
···
1462
1419
1463
1420
if doc_content.search(line):
1464
1421
cont = doc_content.group(1)
1465
-
1466
-
if cont == "":
1467
-
self.entry.contents += "\n"
1468
-
else:
1469
-
if self.state == state.SPECIAL_SECTION:
1470
-
if self.entry.leading_space is None:
1471
-
r = KernRe(r'^(\s+)')
1472
-
if r.match(cont):
1473
-
self.entry.leading_space = len(r.group(1))
1474
-
else:
1475
-
self.entry.leading_space = 0
1476
-
1477
-
# Double-check if leading space are realy spaces
1478
-
pos = 0
1479
-
for i in range(0, self.entry.leading_space):
1480
-
if cont[i] != " ":
1481
-
break
1482
-
pos += 1
1483
-
1484
-
cont = cont[pos:]
1485
-
1486
-
# NEW LOGIC:
1487
-
# In case it is different, update it
1488
-
if self.entry.leading_space != pos:
1489
-
self.entry.leading_space = pos
1490
-
1491
-
self.entry.contents += cont + "\n"
1492
-
return
1493
-
1494
-
# Unknown line, ignore
1495
-
self.emit_msg(ln, f"bad line: {line}")
1422
+
self.entry.contents += cont + "\n"
1423
+
else:
1424
+
# Unknown line, ignore
1425
+
self.emit_msg(ln, f"bad line: {line}")
1496
1426
1497
1427
def process_inline(self, ln, line):
1498
1428
"""STATE_INLINE: docbook comments within a prototype."""