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: rework the handling of SPECIAL_SECTION

Move the recognition of this state to when we enter it, rather than when we
exit, eliminating some twisty logic along the way.

Some changes in output do result from this shift, generally for kerneldoc
comments that do not quite fit the format. See, for example,
struct irqdomain. As far as I can tell, the new behavior is more correct
in each case.

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

Jonathan Corbet e65d54e1 99327067

+20 -28
+20 -28
scripts/lib/kdoc/kdoc_parser.py
··· 1316 1316 def is_new_section(self, ln, line): 1317 1317 if doc_sect.search(line): 1318 1318 self.entry.in_doc_sect = True 1319 + self.state = state.BODY 1320 + # 1321 + # Pick out the name of our new section, tweaking it if need be. 1322 + # 1319 1323 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"]: 1324 + if newsection.lower() == 'description': 1325 + newsection = 'Description' 1326 + elif newsection.lower() == 'context': 1327 + newsection = 'Context' 1328 + self.state = state.SPECIAL_SECTION 1329 + elif newsection.lower() in ["@return", "@returns", 1330 + "return", "returns"]: 1327 1331 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() 1332 + self.state = state.SPECIAL_SECTION 1333 + elif newsection[0] == '@': 1334 + self.state = state.SPECIAL_SECTION 1335 + # 1336 + # Initialize the contents, and get the new section going. 1337 + # 1334 1338 newcontents = doc_sect.group(2) 1335 1339 if not newcontents: 1336 1340 newcontents = "" ··· 1348 1344 self.entry.contents = newcontents.lstrip() 1349 1345 if self.entry.contents: 1350 1346 self.entry.contents += "\n" 1351 - 1352 - self.state = state.BODY 1353 1347 return True 1354 1348 return False 1355 1349 ··· 1397 1395 """ 1398 1396 STATE_SPECIAL_SECTION: a section ending with a blank line 1399 1397 """ 1400 - if KernRe(r"\s*\*\s*\S").match(line): 1398 + if KernRe(r"\s*\*\s*$").match(line): 1401 1399 self.entry.begin_section(ln, dump = True) 1400 + self.state = state.BODY 1402 1401 self.process_body(ln, line) 1403 1402 1404 1403 def process_body(self, ln, line): ··· 1427 1424 cont = doc_content.group(1) 1428 1425 1429 1426 if cont == "": 1430 - if self.entry.section == self.section_context: 1431 - self.entry.begin_section(ln, dump = True) 1432 - self.state = state.BODY 1433 - else: 1434 - if self.entry.section != SECTION_DEFAULT: 1435 - self.state = state.SPECIAL_SECTION 1436 - else: 1437 - self.state = state.BODY 1438 - 1439 1427 self.entry.contents += "\n" 1440 - 1441 1428 else: 1442 - if self.entry.section.startswith('@') or \ 1443 - self.entry.section == self.section_context: 1429 + if self.state == state.SPECIAL_SECTION: 1444 1430 if self.entry.leading_space is None: 1445 1431 r = KernRe(r'^(\s+)') 1446 1432 if r.match(cont):