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>
---
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(-)

diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
index 2376f180b1fa..2acf9f6e5c35 100644
--- a/scripts/lib/kdoc/kdoc_parser.py
+++ b/scripts/lib/kdoc/kdoc_parser.py
@@ -254,7 +254,7 @@ SECTION_DEFAULT = "Description"  # default section
 
 class KernelEntry:
 
-    def __init__(self, config, ln):
+    def __init__(self, config, fname, ln):
         self.config = config
 
         self._contents = []
@@ -274,6 +274,8 @@ class KernelEntry:
 
         self.leading_space = None
 
+        self.fname = fname
+
         # State flags
         self.brcount = 0
         self.declaration_start_line = ln + 1
@@ -288,9 +290,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
@@ -336,7 +340,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:
@@ -387,15 +391,15 @@ class KernelDoc:
             self.emit_msg(0,
                           'Python 3.7 or later is required for correct results')
 
-    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:
@@ -440,7 +444,7 @@ class KernelDoc:
         variables used by the state machine.
         """
 
-        self.entry = KernelEntry(self.config, ln)
+        self.entry = KernelEntry(self.config, self.fname, ln)
 
         # State flags
         self.state = state.NORMAL

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

Best regards,
--  
Jacob Keller <jacob.e.keller@intel.com>

Jacob Keller <jacob.e.keller@intel.com> writes:

> 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.

So I would like to thrash the logging more thoroughly in a number of
ways.  Having separate log() and warn() functions would be a good start.

Failing that, though, this looks to me like a reasonable fix.

However: it doesn't apply to docs-next.  I can try to make a version
that does in the next day or three, but if you could respin it against
the current docs, that would be great...?

Thanks,

jon

On 10/30/2025 9:54 AM, Jonathan Corbet wrote:
> Jacob Keller <jacob.e.keller@intel.com> writes:
> 
>> 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.
> 
> So I would like to thrash the logging more thoroughly in a number of
> ways.  Having separate log() and warn() functions would be a good start.
> 

I do agree the current situation is a bit messy. But I'll leave
improving that up to those more involved in maintaining the tool.

> Failing that, though, this looks to me like a reasonable fix.
> 

Great.

> However: it doesn't apply to docs-next.  I can try to make a version
> that does in the next day or three, but if you could respin it against
> the current docs, that would be great...?
> 

Hm. I was able to apply it cleanly yesterday. I will send a v2 based on
docs-next this afternoon.

> Thanks,
> 
> jon

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@intel.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.

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

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@intel.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.

> 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.

> Thanks.

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@intel.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

On 10/29/2025 1:39 PM, Randy Dunlap wrote:
> On 10/29/25 1:04 PM, Jacob Keller wrote:
>>> 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/
> 
Thanks. I don't see any fix from him on the Lore archives, and I don't
see one on linux-next or docs-next, but at least its obvious Mauro is
aware of the issue.

Either way, we can wait for Mauro's response here and take or leave this
patch, whichever way he prefers.

Regards,
Jake

On 10/29/2025 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@intel.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 rebased clean onto docs-next, so if there is a fix its not on that
tree as of 90b6a53073df ("Documentation: fix reference to
PR_SPEC_L1D_FLUSH")

Thanks,
Jake