admin/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux.git synced 2025-12-07 20:06:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: kdoc: fix duplicate section warning message

Browse Source 
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: e3b42e94cf ("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>
This commit is contained in:
Jacob Keller
2025-10-30 12:58:32 -07:00
committed by Jonathan Corbet
parent b4ff1f611b
commit e5e7ca66a7
1 changed files with 10 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
scripts/lib/kdoc/kdoc_parser.py
View File

@@ -275,6 +275,8 @@ class KernelEntry:
self.leading_space = None
self.fname = fname
# State flags
self.brcount = 0
self.declaration_start_line = ln + 1
@@ -289,9 +291,11 @@ class KernelEntry:
return '\n'.join(self._contents) + '\n'
# TODO: rename to emit_message after removal of kernel-doc.pl
def emit_msg(self, log_msg, warning=True):
def emit_msg(self, ln, msg, *, warning=True):
"""Emit a message"""
log_msg = f"{self.fname}:{ln} {msg}"
if not warning:
self.config.log.info(log_msg)
return
@@ -337,7 +341,7 @@ class KernelEntry:
# Only warn on user-specified duplicate section names
if name != SECTION_DEFAULT:
self.emit_msg(self.new_start_line,
f"duplicate section name '{name}'\n")
f"duplicate section name '{name}'")
# Treat as a new paragraph - add a blank line
self.sections[name] += '\n' + contents
else:
@@ -393,15 +397,15 @@ class KernelDoc:
'Python 3.7 or later is required for correct results')
python_warning = True
def emit_msg(self, ln, msg, warning=True):
def emit_msg(self, ln, msg, *, warning=True):
"""Emit a message"""
log_msg = f"{self.fname}:{ln} {msg}"
if self.entry:
self.entry.emit_msg(log_msg, warning)
self.entry.emit_msg(ln, msg, warning=warning)
return
log_msg = f"{self.fname}:{ln} {msg}"
if warning:
self.config.log.warning(log_msg)
else: