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: Move content handling into KernelEntry

Rather than having other code mucking around with this bit of internal
state, encapsulate it internally. Accumulate the description as a list of
strings, joining them at the end, which is a more efficient way of building
the text.

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

Jonathan Corbet 1e2a79ca 4eaf6120

+30 -32
+30 -32
scripts/lib/kdoc/kdoc_parser.py
··· 128 128 def __init__(self, config, ln): 129 129 self.config = config 130 130 131 - self.contents = "" 131 + self._contents = [] 132 132 self.function = "" 133 133 self.sectcheck = "" 134 134 self.struct_actual = "" ··· 152 152 # State flags 153 153 self.brcount = 0 154 154 self.declaration_start_line = ln + 1 155 + 156 + # 157 + # Management of section contents 158 + # 159 + def add_text(self, text): 160 + self._contents.append(text) 161 + 162 + def contents(self): 163 + return '\n'.join(self._contents) + '\n' 155 164 156 165 # TODO: rename to emit_message after removal of kernel-doc.pl 157 166 def emit_msg(self, log_msg, warning=True): ··· 189 180 """ 190 181 Dumps section contents to arrays/hashes intended for that purpose. 191 182 """ 192 - 183 + # 184 + # If we have accumulated no contents in the default ("description") 185 + # section, don't bother. 186 + # 187 + if self.section == SECTION_DEFAULT and not self._contents: 188 + return 193 189 name = self.section 194 - contents = self.contents 190 + contents = self.contents() 195 191 196 192 if type_param.match(name): 197 193 name = type_param.group(1) ··· 220 206 if name != SECTION_DEFAULT: 221 207 self.emit_msg(self.new_start_line, 222 208 f"duplicate section name '{name}'\n") 223 - self.sections[name] += contents 209 + # Treat as a new paragraph - add a blank line 210 + self.sections[name] += '\n' + contents 224 211 else: 225 212 self.sections[name] = contents 226 213 self.sectionlist.append(name) ··· 232 217 233 218 if start_new: 234 219 self.section = SECTION_DEFAULT 235 - self.contents = "" 220 + self._contents = [] 236 221 237 222 238 223 class KernelDoc: ··· 1349 1334 newcontents = doc_sect.group(2) 1350 1335 if not newcontents: 1351 1336 newcontents = "" 1352 - 1353 - if self.entry.contents.strip("\n"): 1354 - self.dump_section() 1355 - 1337 + self.dump_section() 1356 1338 self.entry.begin_section(ln, newsection) 1357 1339 self.entry.leading_space = None 1358 1340 1359 - self.entry.contents = newcontents.lstrip() 1360 - if self.entry.contents: 1361 - self.entry.contents += "\n" 1341 + self.entry.add_text(newcontents.lstrip()) 1362 1342 return True 1363 1343 return False 1364 1344 ··· 1395 1385 # 1396 1386 if cont == "": 1397 1387 self.state = state.BODY 1398 - self.entry.contents += "\n" # needed? 1399 1388 # 1400 1389 # Otherwise we have more of the declaration section to soak up. 1401 1390 # ··· 1416 1407 # 1417 1408 if KernRe(r"\s*\*\s*$").match(line): 1418 1409 self.entry.begin_section(ln, dump = True) 1419 - self.entry.contents += '\n' 1420 1410 self.state = state.BODY 1421 1411 return 1422 1412 # ··· 1452 1444 # 1453 1445 # Add the trimmed result to the section and we're done. 1454 1446 # 1455 - self.entry.contents += cont[self.entry.leading_space:] + '\n' 1447 + self.entry.add_text(cont[self.entry.leading_space:]) 1456 1448 else: 1457 1449 # Unknown line, ignore 1458 1450 self.emit_msg(ln, f"bad line: {line}") ··· 1466 1458 1467 1459 if doc_content.search(line): 1468 1460 cont = doc_content.group(1) 1469 - self.entry.contents += cont + "\n" 1461 + self.entry.add_text(cont) 1470 1462 else: 1471 1463 # Unknown line, ignore 1472 1464 self.emit_msg(ln, f"bad line: {line}") ··· 1478 1470 doc_inline_sect.search(line): 1479 1471 self.entry.begin_section(ln, doc_inline_sect.group(1)) 1480 1472 1481 - self.entry.contents = doc_inline_sect.group(2).lstrip() 1482 - if self.entry.contents != "": 1483 - self.entry.contents += "\n" 1484 - 1473 + self.entry.add_text(doc_inline_sect.group(2).lstrip()) 1485 1474 self.inline_doc_state = state.INLINE_TEXT 1486 1475 # Documentation block end */ 1487 1476 return 1488 1477 1489 1478 if doc_inline_end.search(line): 1490 - if self.entry.contents not in ["", "\n"]: 1491 - self.dump_section() 1492 - 1479 + self.dump_section() 1493 1480 self.state = state.PROTO 1494 1481 self.inline_doc_state = state.INLINE_NA 1495 1482 return 1496 1483 1497 1484 if doc_content.search(line): 1498 1485 if self.inline_doc_state == state.INLINE_TEXT: 1499 - self.entry.contents += doc_content.group(1) + "\n" 1500 - if not self.entry.contents.strip(" ").rstrip("\n"): 1501 - self.entry.contents = "" 1486 + self.entry.add_text(doc_content.group(1)) 1502 1487 1503 1488 elif self.inline_doc_state == state.INLINE_NAME: 1504 1489 self.emit_msg(ln, ··· 1669 1668 1670 1669 if doc_inline_oneline.search(line): 1671 1670 self.entry.begin_section(ln, doc_inline_oneline.group(1)) 1672 - self.entry.contents = doc_inline_oneline.group(2) 1673 - 1674 - if self.entry.contents != "": 1675 - self.entry.contents += "\n" 1676 - self.dump_section(start_new=False) 1671 + self.entry.add_text(doc_inline_oneline.group(2)) 1672 + self.dump_section() 1677 1673 1678 1674 elif doc_inline_start.search(line): 1679 1675 self.state = state.INLINE ··· 1694 1696 self.reset_state(ln) 1695 1697 1696 1698 elif doc_content.search(line): 1697 - self.entry.contents += doc_content.group(1) + "\n" 1699 + self.entry.add_text(doc_content.group(1)) 1698 1700 1699 1701 def parse_export(self): 1700 1702 """