Message-ID: <f226af11-adbb-444f-9322-1dd3116321f7@infradead.org>
Date: Wed, 29 Oct 2025 13:39:55 -0700
From: Randy Dunlap <rdunlap@...radead.org>
To: Jacob Keller <jacob.e.keller@...el.com>, Jonathan Corbet
 <corbet@....net>, Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
 Jakub Kicinski <kuba@...nel.org>
Cc: netdev@...r.kernel.org, linux-doc@...r.kernel.org,
 linux-kernel@...r.kernel.org
Subject: Re: [PATCH] docs: kdoc: fix duplicate section warning message



On 10/29/25 1:04 PM, Jacob Keller wrote:
> 
> 
> On 10/29/2025 12:45 PM, Randy Dunlap wrote:
>> 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@...el.com>
>>> ---
>>> 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@kernel.org/
>>>
>>> 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.
>>
> 
> Hm. Its e53642b87a4f ("Merge tag 'v6.18-rc3-smb-server-fixes' of
> git://git.samba.org/ksmbd") which was the top of
> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git as of
> when I made the commit. I wasn't sure which tree to base on since I'm
> not a regular contributor to the docs stuff, so I just based on Linus's
> tree instead of linux-next.
> 
>> 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.)
> 
> I searched mail archives but didn't find a report, so hence the patch.
> If this already has a proper fix thats fine.
> 

It was discussed here and Mauro said that he sent a patch but I still
see those warnings in linux-next-20251029.

https://lore.kernel.org/all/jd5uf3ud2khep2oqyos3uhfkuptvcm4zgboelfxjut43bxpr6o@ye24ej7g3p7n/

>> If not, then this will need to apply to docs-next AFAIK.
>>  
> 
> Ok, I can rebase if it is necessary. I'll check that out, and can send a
> v2 if Mauro hasn't already fixed it somehow else.
> 
>> 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.
>>
> 
> Yep, thats an issue with the header. They're doing something weird by
> doing some sort of sub-documentation for each method of an ops struct. I
> don't really know what the best fix is for this doc file, nor do I
> particularly care. I just used it as an example because its the one that
> we ran into while looking at output from the netdev testing infrastructure.

-- 
~Randy

Powered by blists - more mailing lists