tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

docs: kdoc: remove the inline states-within-a-state

The processing of inline kerneldoc comments is a state like the rest, but
it was implemented as a set of separate substates. Just remove the
substate logic and make the inline states normal ones like the rest.

INLINE_ERROR was never actually used for anything, so just take it out.

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/20250627184000.132291-8-corbet@lwn.net

Jonathan Corbet 8976f993 388f4da2

+13 -30
+13 -30
scripts/lib/kdoc/kdoc_parser.py
··· 91 91 SPECIAL_SECTION = 4 # doc section ending with a blank line 92 92 PROTO = 5 # scanning prototype 93 93 DOCBLOCK = 6 # documentation block 94 - INLINE = 7 # gathering doc outside main block 94 + INLINE_NAME = 7 # gathering doc outside main block 95 + INLINE_TEXT = 8 # reading the body of inline docs 95 96 96 97 name = [ 97 98 "NORMAL", ··· 102 101 "SPECIAL_SECTION", 103 102 "PROTO", 104 103 "DOCBLOCK", 105 - "INLINE", 104 + "INLINE_NAME", 105 + "INLINE_TEXT", 106 106 ] 107 107 108 - # Inline documentation state 109 - INLINE_NA = 0 # not applicable ($state != INLINE) 110 - INLINE_NAME = 1 # looking for member name (@foo:) 111 - INLINE_TEXT = 2 # looking for member documentation 112 - INLINE_ERROR = 3 # error - Comment without header was found. 113 - # Spit a warning as it's not 114 - # proper kernel-doc and ignore the rest. 115 - 116 - inline_name = [ 117 - "", 118 - "_NAME", 119 - "_TEXT", 120 - "_ERROR", 121 - ] 122 108 123 109 SECTION_DEFAULT = "Description" # default section 124 110 ··· 234 246 235 247 # Initial state for the state machines 236 248 self.state = state.NORMAL 237 - self.inline_doc_state = state.INLINE_NA 238 249 239 250 # Store entry currently being processed 240 251 self.entry = None ··· 310 323 311 324 # State flags 312 325 self.state = state.NORMAL 313 - self.inline_doc_state = state.INLINE_NA 314 326 315 327 def push_parameter(self, ln, decl_type, param, dtype, 316 328 org_arg, declaration_name): ··· 1451 1465 def process_inline(self, ln, line): 1452 1466 """STATE_INLINE: docbook comments within a prototype.""" 1453 1467 1454 - if self.inline_doc_state == state.INLINE_NAME and \ 1468 + if self.state == state.INLINE_NAME and \ 1455 1469 doc_inline_sect.search(line): 1456 1470 self.entry.begin_section(ln, doc_inline_sect.group(1)) 1457 1471 1458 1472 self.entry.add_text(doc_inline_sect.group(2).lstrip()) 1459 - self.inline_doc_state = state.INLINE_TEXT 1473 + self.state = state.INLINE_TEXT 1460 1474 # Documentation block end */ 1461 1475 return 1462 1476 1463 1477 if doc_inline_end.search(line): 1464 1478 self.dump_section() 1465 1479 self.state = state.PROTO 1466 - self.inline_doc_state = state.INLINE_NA 1467 1480 return 1468 1481 1469 1482 if doc_content.search(line): 1470 - if self.inline_doc_state == state.INLINE_TEXT: 1483 + if self.state == state.INLINE_TEXT: 1471 1484 self.entry.add_text(doc_content.group(1)) 1472 1485 1473 - elif self.inline_doc_state == state.INLINE_NAME: 1486 + elif self.state == state.INLINE_NAME: 1474 1487 self.emit_msg(ln, 1475 1488 f"Incorrect use of kernel-doc format: {line}") 1476 - 1477 - self.inline_doc_state = state.INLINE_ERROR 1489 + self.state = state.PROTO 1478 1490 1479 1491 def syscall_munge(self, ln, proto): # pylint: disable=W0613 1480 1492 """ ··· 1648 1664 self.dump_section() 1649 1665 1650 1666 elif doc_inline_start.search(line): 1651 - self.state = state.INLINE 1652 - self.inline_doc_state = state.INLINE_NAME 1667 + self.state = state.INLINE_NAME 1653 1668 1654 1669 elif self.entry.decl_type == 'function': 1655 1670 self.process_proto_function(ln, line) ··· 1699 1716 state.BODY: process_body, 1700 1717 state.DECLARATION: process_decl, 1701 1718 state.SPECIAL_SECTION: process_special, 1702 - state.INLINE: process_inline, 1719 + state.INLINE_NAME: process_inline, 1720 + state.INLINE_TEXT: process_inline, 1703 1721 state.PROTO: process_proto, 1704 1722 state.DOCBLOCK: process_docblock, 1705 1723 } ··· 1740 1756 prev = "" 1741 1757 prev_ln = None 1742 1758 1743 - self.config.log.debug("%d %s%s: %s", 1759 + self.config.log.debug("%d %s: %s", 1744 1760 ln, state.name[self.state], 1745 - state.inline_name[self.inline_doc_state], 1746 1761 line) 1747 1762 1748 1763 # This is an optimization over the original script.