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: some final touches for process_name()

Add some comments to process_name() to cover its broad phases of operation,
and slightly restructure the if/then/else structure to remove some early
returns.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250606163438.229916-10-corbet@lwn.net

Jonathan Corbet 8666a352 0682bde2

+20 -13
+20 -13
scripts/lib/kdoc/kdoc_parser.py
··· 1227 1227 """ 1228 1228 STATE_NAME: Looking for the "name - description" line 1229 1229 """ 1230 - 1230 + # 1231 + # Check for a DOC: block and handle them specially. 1232 + # 1231 1233 if doc_block.search(line): 1232 1234 self.entry.new_start_line = ln 1233 1235 ··· 1240 1238 1241 1239 self.entry.identifier = self.entry.section 1242 1240 self.state = state.DOCBLOCK 1243 - return 1244 - 1245 - if doc_decl.search(line): 1241 + # 1242 + # Otherwise we're looking for a normal kerneldoc declaration line. 1243 + # 1244 + elif doc_decl.search(line): 1246 1245 self.entry.identifier = doc_decl.group(1) 1247 1246 1248 1247 # Test for data declaration ··· 1264 1261 f"This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n{line}") 1265 1262 self.state = state.NORMAL 1266 1263 return 1267 - 1268 - self.entry.identifier = self.entry.identifier.strip(" ") 1269 - 1264 + # 1265 + # OK, set up for a new kerneldoc entry. 1266 + # 1270 1267 self.state = state.BODY 1271 - 1268 + self.entry.identifier = self.entry.identifier.strip(" ") 1272 1269 # if there's no @param blocks need to set up default section here 1273 1270 self.entry.section = SECTION_DEFAULT 1274 1271 self.entry.new_start_line = ln + 1 1275 - 1272 + # 1273 + # Find the description portion, which *should* be there but 1274 + # isn't always. 1275 + # (We should be able to capture this from the previous parsing - someday) 1276 + # 1276 1277 r = KernRe("[-:](.*)") 1277 1278 if r.search(line): 1278 1279 self.entry.declaration_purpose = trim_whitespace(r.group(1)) ··· 1297 1290 self.emit_msg(ln, 1298 1291 f"Scanning doc for {self.entry.decl_type} {self.entry.identifier}", 1299 1292 warning=False) 1300 - 1301 - return 1302 - 1293 + # 1303 1294 # Failed to find an identifier. Emit a warning 1304 - self.emit_msg(ln, f"Cannot find identifier on line:\n{line}") 1295 + # 1296 + else: 1297 + self.emit_msg(ln, f"Cannot find identifier on line:\n{line}") 1305 1298 1306 1299 def process_body(self, ln, line): 1307 1300 """