Re: [PATCH] docs: kdoc: fix duplicate section warning message

[Randy Dunlap]

Hi Jacob,

On 10/29/25 11:30 AM, Jacob Keller wrote:
> 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@xxxxxxxxx>
> ---
> We recently discovered this while working on some netdev text
> infrastructure. All of the duplicate section warnings are not being logged
> properly, which was confusing the warning comparison logic we have for
> testing patches in NIPA.
> 
> This appears to have been caused by the optimizations in:
> https://lore.kernel.org/all/cover.1745564565.git.mchehab+huawei@xxxxxxxxxx/
> 
> Before this fix:
> $ ./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'
> 
> After this fix:
> $ ./scripts/kernel-doc -Wall -none 'include/linux/virtio_config.h'
> Warning: include/linux/virtio_config.h:174 duplicate section name 'Return'
> Warning: include/linux/virtio_config.h:184 duplicate section name 'Return'
> Warning: include/linux/virtio_config.h:190 duplicate section name 'Return'
> 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'
> ---
>  scripts/lib/kdoc/kdoc_parser.py | 20 ++++++++++++--------
>  1 file changed, 12 insertions(+), 8 deletions(-)
> 

> ---
> base-commit: e53642b87a4f4b03a8d7e5f8507fc3cd0c595ea6
> change-id: 20251029-jk-fix-kernel-doc-duplicate-return-warning-bd57ea39c628

What is that base-commit? I don't have it.
It doesn't apply to linux-next (I didn't check docs-next).
It does apply cleanly to kernel v6.18-rc3.

and it does fix the Warning messages to be something useful. Thanks.

We'll have to see if Mauro already has a fix for this. (I reported
it a couple of weeks ago.)
If not, then this will need to apply to docs-next AFAIK.

And not a problem with this patch, but those Returns: lines for
each callback function shouldn't be there as Returns:. This is a
struct declaration, not a function (or macro) declaration/definition.

Thanks.
-- 
~Randy