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: fix duplicate section warning message

The python version of the kernel-doc parser emits some strange warnings
with just a line number in certain cases:

$ ./scripts/kernel-doc -Wall -none 'include/linux/virtio_config.h'
Warning: 174
Warning: 184
Warning: 190
Warning: include/linux/virtio_config.h:226 No description found for return value of '__virtio_test_bit'
Warning: include/linux/virtio_config.h:259 No description found for return value of 'virtio_has_feature'
Warning: include/linux/virtio_config.h:283 No description found for return value of 'virtio_has_dma_quirk'
Warning: include/linux/virtio_config.h:392 No description found for return value of 'virtqueue_set_affinity'

I eventually tracked this down to the lone call of emit_msg() in the
KernelEntry class, which looks like:

self.emit_msg(self.new_start_line, f"duplicate section name '{name}'\n")

This looks like all the other emit_msg calls. Unfortunately, the definition
within the KernelEntry class takes only a message parameter and not a line
number. The intended message is passed as the warning!

Pass the filename to the KernelEntry class, and use this to build the log
message in the same way as the KernelDoc class does.

To avoid future errors, mark the warning parameter for both emit_msg
definitions as a keyword-only argument. This will prevent accidentally
passing a string as the warning parameter in the future.

Also fix the call in dump_section to avoid an unnecessary additional
newline.

Fixes: e3b42e94cf10 ("scripts/lib/kdoc/kdoc_parser.py: move kernel entry to a class")
Signed-off-by: Jacob Keller <jacob.e.keller@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251030-jk-fix-kernel-doc-duplicate-return-warning-v2-1-ec4b5c662881@intel.com>

authored by

Jacob Keller and committed by
Jonathan Corbet e5e7ca66 b4ff1f61

+10 -6
+10 -6
scripts/lib/kdoc/kdoc_parser.py
··· 275 275 276 276 self.leading_space = None 277 277 278 + self.fname = fname 279 + 278 280 # State flags 279 281 self.brcount = 0 280 282 self.declaration_start_line = ln + 1 ··· 291 289 return '\n'.join(self._contents) + '\n' 292 290 293 291 # TODO: rename to emit_message after removal of kernel-doc.pl 294 - def emit_msg(self, log_msg, warning=True): 292 + def emit_msg(self, ln, msg, *, warning=True): 295 293 """Emit a message""" 294 + 295 + log_msg = f"{self.fname}:{ln} {msg}" 296 296 297 297 if not warning: 298 298 self.config.log.info(log_msg) ··· 341 337 # Only warn on user-specified duplicate section names 342 338 if name != SECTION_DEFAULT: 343 339 self.emit_msg(self.new_start_line, 344 - f"duplicate section name '{name}'\n") 340 + f"duplicate section name '{name}'") 345 341 # Treat as a new paragraph - add a blank line 346 342 self.sections[name] += '\n' + contents 347 343 else: ··· 397 393 'Python 3.7 or later is required for correct results') 398 394 python_warning = True 399 395 400 - def emit_msg(self, ln, msg, warning=True): 396 + def emit_msg(self, ln, msg, *, warning=True): 401 397 """Emit a message""" 402 398 403 - log_msg = f"{self.fname}:{ln} {msg}" 404 - 405 399 if self.entry: 406 - self.entry.emit_msg(log_msg, warning) 400 + self.entry.emit_msg(ln, msg, warning=warning) 407 401 return 402 + 403 + log_msg = f"{self.fname}:{ln} {msg}" 408 404 409 405 if warning: 410 406 self.config.log.warning(log_msg)