linux-next: build warnings after merge of Linus' tree

linux-next: build warnings after merge of Linus' tree

[Stephen Rothwell]

[-- Attachment #1: Type: text/plain, Size: 756 bytes --]

Hi all,

After merging Linus' tree, today's linux-next build (htmldocs) produced
these warnings:

include/linux/of.h:1211: warning: Function parameter or member 'output' not described in 'of_property_read_string_index'
include/linux/of.h:1211: warning: Excess function parameter 'out_string' description in 'of_property_read_string_index'

Introduced by commit

  a87fa1d81a9f ("of: Fix overflow bug in string property parsing functions")

include/linux/of.h:1480: warning: cannot understand function prototype: 'enum of_overlay_notify_action '

Introduced by commit

  39a842e22c1b ("of/overlay: add of overlay notifications")

I assume that these warnings have turned up now due to better(?) tooling.

-- 
Cheers,
Stephen Rothwell

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: linux-next: build warnings after merge of Linus' tree

[Stephen Rothwell]

[-- Attachment #1: Type: text/plain, Size: 729 bytes --]

Hi all,

On Mon, 29 Mar 2021 20:04:10 +1100 Stephen Rothwell <sfr@canb.auug.org.au> wrote:
> 
> After merging Linus' tree, today's linux-next build (htmldocs) produced
> these warnings:
> 
> include/linux/of.h:1211: warning: Function parameter or member 'output' not described in 'of_property_read_string_index'
> include/linux/of.h:1211: warning: Excess function parameter 'out_string' description in 'of_property_read_string_index'
> 
> Introduced by commit
> 
>   a87fa1d81a9f ("of: Fix overflow bug in string property parsing functions")
> 
> I assume that these warnings have turned up now due to better(?) tooling.

I am still seeing these warnings (as of next-20210420).

-- 
Cheers,
Stephen Rothwell

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: linux-next: build warnings after merge of Linus' tree

[Rob Herring]

On Wed, Apr 21, 2021 at 1:23 AM Stephen Rothwell <sfr@canb.auug.org.au> wrote:
>
> Hi all,
>
> On Mon, 29 Mar 2021 20:04:10 +1100 Stephen Rothwell <sfr@canb.auug.org.au> wrote:
> >
> > After merging Linus' tree, today's linux-next build (htmldocs) produced
> > these warnings:
> >
> > include/linux/of.h:1211: warning: Function parameter or member 'output' not described in 'of_property_read_string_index'
> > include/linux/of.h:1211: warning: Excess function parameter 'out_string' description in 'of_property_read_string_index'
> >
> > Introduced by commit
> >
> >   a87fa1d81a9f ("of: Fix overflow bug in string property parsing functions")
> >
> > I assume that these warnings have turned up now due to better(?) tooling.
>
> I am still seeing these warnings (as of next-20210420).

A fix is now in my tree.

Rob

linux-next: build warnings after merge of Linus' tree

[Stephen Rothwell]

[-- Attachment #1: Type: text/plain, Size: 574 bytes --]

Hi all,

While building Linus' tree, today's linux-next build (htmldocs)
produced these warnings:

kernel/sched/core.c:11496: warning: Cannot understand  * @cid_lock: Guarantee forward-progress of cid allocation.
 on line 11496 - I thought it was a doc line
kernel/sched/core.c:11505: warning: Cannot understand  * @use_cid_lock: Select cid allocation behavior: lock-free vs spinlock.
 on line 11505 - I thought it was a doc line

Introduced by commit

  223baf9d17f2 ("sched: Fix performance regression introduced by mm_cid")

-- 
Cheers,
Stephen Rothwell

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: linux-next: build warnings after merge of Linus' tree

[Randy Dunlap]

On 5/7/23 21:49, Stephen Rothwell wrote:
> Hi all,
> 
> While building Linus' tree, today's linux-next build (htmldocs)
> produced these warnings:
> 
> kernel/sched/core.c:11496: warning: Cannot understand  * @cid_lock: Guarantee forward-progress of cid allocation.
>  on line 11496 - I thought it was a doc line
> kernel/sched/core.c:11505: warning: Cannot understand  * @use_cid_lock: Select cid allocation behavior: lock-free vs spinlock.
>  on line 11505 - I thought it was a doc line
> 
> Introduced by commit
> 
>   223baf9d17f2 ("sched: Fix performance regression introduced by mm_cid")
> 

I have sent a patch:
  https://lore.kernel.org/lkml/20230428031111.322-1-rdunlap@infradead.org
but haven't seen any replies to it (possibly due to the merge window or travel).

-- 
~Randy

Re: linux-next: build warnings after merge of Linus' tree

[Randy Dunlap]

On 5/7/23 21:52, Randy Dunlap wrote:
> 
> 
> On 5/7/23 21:49, Stephen Rothwell wrote:
>> Hi all,
>>
>> While building Linus' tree, today's linux-next build (htmldocs)
>> produced these warnings:
>>
>> kernel/sched/core.c:11496: warning: Cannot understand  * @cid_lock: Guarantee forward-progress of cid allocation.
>>  on line 11496 - I thought it was a doc line
>> kernel/sched/core.c:11505: warning: Cannot understand  * @use_cid_lock: Select cid allocation behavior: lock-free vs spinlock.
>>  on line 11505 - I thought it was a doc line
>>
>> Introduced by commit
>>
>>   223baf9d17f2 ("sched: Fix performance regression introduced by mm_cid")
>>
> 
> I have sent a patch:
>   https://lore.kernel.org/lkml/20230428031111.322-1-rdunlap@infradead.org
> but haven't seen any replies to it (possibly due to the merge window or travel).
> 

Oops, Peter did reply, but no info on merging it.

-- 
~Randy

Re: linux-next: build warnings after merge of Linus' tree

[Peter Zijlstra]

On Sun, May 07, 2023 at 09:52:22PM -0700, Randy Dunlap wrote:
> 
> 
> On 5/7/23 21:49, Stephen Rothwell wrote:
> > Hi all,
> > 
> > While building Linus' tree, today's linux-next build (htmldocs)
> > produced these warnings:
> > 
> > kernel/sched/core.c:11496: warning: Cannot understand  * @cid_lock: Guarantee forward-progress of cid allocation.
> >  on line 11496 - I thought it was a doc line
> > kernel/sched/core.c:11505: warning: Cannot understand  * @use_cid_lock: Select cid allocation behavior: lock-free vs spinlock.
> >  on line 11505 - I thought it was a doc line
> > 
> > Introduced by commit
> > 
> >   223baf9d17f2 ("sched: Fix performance regression introduced by mm_cid")
> > 
> 
> I have sent a patch:
>   https://lore.kernel.org/lkml/20230428031111.322-1-rdunlap@infradead.org
> but haven't seen any replies to it (possibly due to the merge window or travel).

I have it, and now that -rc1 is out the door, I'll queue it for -urgent.

linux-next: build warnings after merge of Linus' tree

[Stephen Rothwell]

[-- Attachment #1: Type: text/plain, Size: 438 bytes --]

Hi all,

After merging Linus' tree, today's linux-next build (x86_64
allmodconfig) produced these warnings:

WARNING: modpost: missing MODULE_DESCRIPTION() in mm/kasan/kasan_test.o
WARNING: modpost: missing MODULE_DESCRIPTION() in lib/tests/slub_kunit.o

Introduced by commits

  6c6c1fc09de3 ("modpost: require a MODULE_DESCRIPTION()")
  6f110a5e4f99 ("Disable SLUB_TINY for build testing")

-- 
Cheers,
Stephen Rothwell

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: linux-next: build warnings after merge of Linus' tree

[Venkat]

On IBM Power9 only below warning is observed. 

WARNING: modpost: missing MODULE_DESCRIPTION() in lib/tests/slub_kunit.o

I have tested the patch and the above reported warning is fixed. Please add below tag.


Tested-by: Venkat Rao Bagalkote <venkat88@linux.ibm.com>

Regards,
Venkat.

Re: linux-next: build warnings after merge of Linus' tree

[Venkat Rao Bagalkote]

I think I have messed up. Please ignore below mail.

On 07/04/25 2:29 pm, Venkat wrote:
> On IBM Power9 only below warning is observed.
>
> WARNING: modpost: missing MODULE_DESCRIPTION() in lib/tests/slub_kunit.o
>
> I have tested the patch and the above reported warning is fixed. Please add below tag.
>
>
> Tested-by: Venkat Rao Bagalkote <venkat88@linux.ibm.com>
>
> Regards,
> Venkat.
>
>
>

linux-next: build warnings after merge of Linus' tree

[Stephen Rothwell]

[-- Attachment #1: Type: text/plain, Size: 700 bytes --]

Hi all,

Today's linux-next build (htmldocs) produced these warnings:

WARNING: /home/sfr/kernels/next/next/include/linux/virtio_config.h:174 duplicate section name 'Return'
WARNING: /home/sfr/kernels/next/next/include/linux/virtio_config.h:184 duplicate section name 'Return'
WARNING: /home/sfr/kernels/next/next/include/linux/virtio_config.h:190 duplicate section name 'Return'

Introduced by commit

  bee8c7c24b73 ("virtio: introduce map ops in virtio core")

but is probably a bug in our scripts as those lines above have "Returns:"
in them, not "Return:".

These have turned up now since a bug was fixed that was repressing a
lot of warnings.

-- 
Cheers,
Stephen Rothwell

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: linux-next: build warnings after merge of Linus' tree

[Mauro Carvalho Chehab]

Em Thu, 13 Nov 2025 12:55:37 +1100
Stephen Rothwell <sfr@canb.auug.org.au> escreveu:

> Hi all,
> 
> Today's linux-next build (htmldocs) produced these warnings:
> 
> WARNING: /home/sfr/kernels/next/next/include/linux/virtio_config.h:174 duplicate section name 'Return'
> WARNING: /home/sfr/kernels/next/next/include/linux/virtio_config.h:184 duplicate section name 'Return'
> WARNING: /home/sfr/kernels/next/next/include/linux/virtio_config.h:190 duplicate section name 'Return'
> 
> Introduced by commit
> 
>   bee8c7c24b73 ("virtio: introduce map ops in virtio core")
> 
> but is probably a bug in our scripts as those lines above have "Returns:"
> in them, not "Return:".

It is not a mistake. What happens is that, when kernel-doc detects
something like:

	/**
...
	 * return: something
...
	 *    returns: else
...
	 */

we have a duplicated section. The regular expression that pick sections
is:

	known_section_names = 'description|context|returns?|notes?|examples?'
	known_sections = KernRe(known_section_names, flags = re.I)
	doc_sect = doc_com + \
	    KernRe(r'\s*(@[.\w]+|@\.\.\.|' + known_section_names + r')\s*:([^:].*)?$',
	           flags=re.I, cache=False)

So, basically, it seeks, inside a kernel-doc comment, in case-insensitive
mode, for:

	"\sreturns?:"

In this specific case, virtio_map_ops is using this pattern multiple
times:

	/**
	 * struct virtio_map_ops - operations for mapping buffer for a virtio device
	 * Note: For transport that has its own mapping logic it must
	 * implements all of the operations
	 * @map_page: map a buffer to the device
	 *      map: metadata for performing mapping
	 *      page: the page that will be mapped by the device
	 *      offset: the offset in the page for a buffer
	 *      size: the buffer size
	 *      dir: mapping direction
	 *      attrs: mapping attributes
	 *      Returns: the mapped address
(first occurrence)
	...
	 * @alloc: alloc a coherent buffer mapping
	 *      map: metadata for performing mapping
	 *      size: the size of the buffer
	 *      map_handle: the mapping address to sync
	 *      gfp: allocation flag (GFP_XXX)
	 *      Returns: virtual address of the allocated buffer
(second occurrence, others follow)

As result, it strips "returns" from members output:

	  **Members**

	  ``map_page``
	    map a buffer to the device
	    map: metadata for performing mapping
	    page: the page that will be mapped by the device
	    offset: the offset in the page for a buffer
	    size: the buffer size
	    dir: mapping direction
	    attrs: mapping attributes

	  ``unmap_page``
	...


And creates a return section with each returns: appended:

	**Return**

	the mapped address

	virtual address of the allocated buffer

	whether the buffer needs synchronization

	the maximum buffer size that can be mapped

which is not what it is expected. Such behavior is there since the Perl
version (and the warning), but a patch for the old version disabled
such warning by default (probably because it was too verbose on that
time).

Btw, if you see struct virtio_config_ops, there instead of "Returns: foo"
they use "Returns foo", which produces the desired output:

	  **Members**
...
	  ``generation``
	    config generation counter (optional)
	    vdev: the virtio_device
	    Returns the config generation counter


So, probably the quickest fix would be do to:

	sed s,Returns:,Returns, -i include/linux/virtio_config.h

> These have turned up now since a bug was fixed that was repressing a
> lot of warnings.

The change actually disabled the warning-suppression logic that
was ported from the Perl script, where a lot of real problems at the
kernel-doc markup were ignored. E.g. those command line arguments:

  -Wreturn, --wreturn   Warns about the lack of a return markup on functions.
  -Wshort-desc, -Wshort-description, --wshort-desc
                        Warns if initial short description is missing
  -Wcontents-before-sections, --wcontents-before-sections
                        
                        Warns if there are contents before sections (deprecated).
                        
                        This option is kept just for backward-compatibility, but it does nothing,
                        neither here nor at the original Perl script.
  -Wall, --wall         Enable all types of warnings

are now ignored, so it outputs as if -Wall was passed to it.


Thanks,
Mauro

Re: linux-next: build warnings after merge of Linus' tree

[Michael S. Tsirkin]

On Thu, Nov 13, 2025 at 12:55:37PM +1100, Stephen Rothwell wrote:
> Hi all,
> 
> Today's linux-next build (htmldocs) produced these warnings:
> 
> WARNING: /home/sfr/kernels/next/next/include/linux/virtio_config.h:174 duplicate section name 'Return'
> WARNING: /home/sfr/kernels/next/next/include/linux/virtio_config.h:184 duplicate section name 'Return'
> WARNING: /home/sfr/kernels/next/next/include/linux/virtio_config.h:190 duplicate section name 'Return'
> 
> Introduced by commit
> 
>   bee8c7c24b73 ("virtio: introduce map ops in virtio core")
> 
> but is probably a bug in our scripts as those lines above have "Returns:"
> in them, not "Return:".
> 
> These have turned up now since a bug was fixed that was repressing a
> lot of warnings.

Indeed. But the rest of header says Returns ... without : so I will just
fix this one to do the same. I also fixed other issues in the comments
in this header while I was at it. Will post shortly.


> -- 
> Cheers,
> Stephen Rothwell

Re: linux-next: build warnings after merge of Linus' tree

[Mauro Carvalho Chehab]

On Thu, Nov 13, 2025 at 03:49:27AM -0500, Michael S. Tsirkin wrote:
> On Thu, Nov 13, 2025 at 12:55:37PM +1100, Stephen Rothwell wrote:
> > Hi all,
> > 
> > Today's linux-next build (htmldocs) produced these warnings:
> > 
> > WARNING: /home/sfr/kernels/next/next/include/linux/virtio_config.h:174 duplicate section name 'Return'
> > WARNING: /home/sfr/kernels/next/next/include/linux/virtio_config.h:184 duplicate section name 'Return'
> > WARNING: /home/sfr/kernels/next/next/include/linux/virtio_config.h:190 duplicate section name 'Return'
> > 
> > Introduced by commit
> > 
> >   bee8c7c24b73 ("virtio: introduce map ops in virtio core")
> > 
> > but is probably a bug in our scripts as those lines above have "Returns:"
> > in them, not "Return:".
> > 
> > These have turned up now since a bug was fixed that was repressing a
> > lot of warnings.
> 
> Indeed. But the rest of header says Returns ... without : so I will just
> fix this one to do the same. I also fixed other issues in the comments
> in this header while I was at it. Will post shortly.

That's the best approach. We could instead change the new section detection
regex to accept just one space at most:

    diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
    index f7dbb0868367..bab0ec3abe31 100644
    --- a/scripts/lib/kdoc/kdoc_parser.py
    +++ b/scripts/lib/kdoc/kdoc_parser.py
    @@ -46,7 +46,7 @@ doc_decl = doc_com + KernRe(r'(\w+)', cache=False)
     known_section_names = 'description|context|returns?|notes?|examples?'
     known_sections = KernRe(known_section_names, flags = re.I)
     doc_sect = doc_com + \
    -    KernRe(r'\s*(@[.\w]+|@\.\.\.|' + known_section_names + r')\s*:([^:].*)?$',
    +    KernRe(r'\s?(@[.\w]+|@\.\.\.|' + known_section_names + r')\s*:([^:].*)?$',
                flags=re.I, cache=False)
 
     doc_content = doc_com_body + KernRe(r'(.*)', cache=False)

(patch not tested)

But, if we do so, someone has to check if this won't cause regressions
elsewhere. I'm almost sure a change like that will break something...

Thanks,
Mauro

Re: linux-next: build warnings after merge of Linus' tree

[Jonathan Corbet]

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

> Em Thu, 13 Nov 2025 12:55:37 +1100
> Stephen Rothwell <sfr@canb.auug.org.au> escreveu:
>
>> Hi all,
>> 
>> Today's linux-next build (htmldocs) produced these warnings:
>> 
>> WARNING: /home/sfr/kernels/next/next/include/linux/virtio_config.h:174 duplicate section name 'Return'
>> WARNING: /home/sfr/kernels/next/next/include/linux/virtio_config.h:184 duplicate section name 'Return'
>> WARNING: /home/sfr/kernels/next/next/include/linux/virtio_config.h:190 duplicate section name 'Return'
>> 
>> Introduced by commit
>> 
>>   bee8c7c24b73 ("virtio: introduce map ops in virtio core")
>> 
>> but is probably a bug in our scripts as those lines above have "Returns:"
>> in them, not "Return:".
>
> It is not a mistake. What happens is that, when kernel-doc detects
> something like:
>
> 	/**
> ...
> 	 * return: something
> ...
> 	 *    returns: else
> ...
> 	 */
>
> we have a duplicated section.

This seems like something we should be able to fix...will try to find
some time to look into it...

jon

Re: linux-next: build warnings after merge of Linus' tree

[Mauro Carvalho Chehab]

Em Thu, 13 Nov 2025 09:23:27 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > Em Thu, 13 Nov 2025 12:55:37 +1100
> > Stephen Rothwell <sfr@canb.auug.org.au> escreveu:
> >  
> >> Hi all,
> >> 
> >> Today's linux-next build (htmldocs) produced these warnings:
> >> 
> >> WARNING: /home/sfr/kernels/next/next/include/linux/virtio_config.h:174 duplicate section name 'Return'
> >> WARNING: /home/sfr/kernels/next/next/include/linux/virtio_config.h:184 duplicate section name 'Return'
> >> WARNING: /home/sfr/kernels/next/next/include/linux/virtio_config.h:190 duplicate section name 'Return'
> >> 
> >> Introduced by commit
> >> 
> >>   bee8c7c24b73 ("virtio: introduce map ops in virtio core")
> >> 
> >> but is probably a bug in our scripts as those lines above have "Returns:"
> >> in them, not "Return:".  
> >
> > It is not a mistake. What happens is that, when kernel-doc detects
> > something like:
> >
> > 	/**
> > ...
> > 	 * return: something
> > ...
> > 	 *    returns: else
> > ...
> > 	 */
> >
> > we have a duplicated section.  
> 
> This seems like something we should be able to fix...will try to find
> some time to look into it...

It is easy to fix, but it may break some things:


	$ git grep -l -E "\* \s+returns?:"
	drivers/edac/i5000_edac.c
	drivers/edac/i5400_edac.c
	drivers/gpu/drm/amd/display/dc/bios/command_table_helper2.c
	drivers/gpu/drm/ingenic/ingenic-ipu.c
	drivers/misc/sgi-gru/grufault.c
	drivers/net/wireless/marvell/libertas/cmd.c
	drivers/net/wireless/marvell/libertas/firmware.c
	drivers/net/wireless/marvell/libertas/if_usb.c
	drivers/net/wireless/marvell/libertas/main.c
	drivers/pci/rom.c
	drivers/scsi/qla2xxx/qla_edif.c
	drivers/tty/moxa.c

And this is only for "return" section. There are also other places
where sections have more than one space. For instance, on 219
files, we have:

	$ git grep -l -E "\* \s+@\w+:"|wc -l
	219

like here:

	drivers/ata/sata_mv.c-/**
	drivers/ata/sata_mv.c- *      mv_print_info - Dump key info to kernel log for perusal.
	drivers/ata/sata_mv.c: *      @host: ATA host to print info about
	drivers/ata/sata_mv.c- *
	drivers/ata/sata_mv.c- *      FIXME: complete this.


So, before changing the regex:

	known_section_names = 'description|context|returns?|notes?|examples?'
	known_sections = KernRe(known_section_names, flags = re.I)
	doc_sect = doc_com + \
-	    KernRe(r'\s*(@[.\w]+|@\.\.\.|' + known_section_names + r')\s*:([^:].*)?$',
+	    KernRe(r'\s?(@[.\w]+|@\.\.\.|' + known_section_names + r')\s*:([^:].*)?$',
	           flags=re.I, cache=False)

to accept only a single space or no spaces, we need to change kernel-doc
markups on lots of files.

Ok, an alternative would be to identify the indentation, but this could
also be problematic.

Thanks,
Mauro

Re: linux-next: build warnings after merge of Linus' tree

[Randy Dunlap]

On 11/13/25 2:01 PM, Mauro Carvalho Chehab wrote:
> Em Thu, 13 Nov 2025 09:23:27 -0700
> Jonathan Corbet <corbet@lwn.net> escreveu:
> 
>> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
>>
>>> Em Thu, 13 Nov 2025 12:55:37 +1100
>>> Stephen Rothwell <sfr@canb.auug.org.au> escreveu:
>>>  
>>>> Hi all,
>>>>
>>>> Today's linux-next build (htmldocs) produced these warnings:
>>>>
>>>> WARNING: /home/sfr/kernels/next/next/include/linux/virtio_config.h:174 duplicate section name 'Return'
>>>> WARNING: /home/sfr/kernels/next/next/include/linux/virtio_config.h:184 duplicate section name 'Return'
>>>> WARNING: /home/sfr/kernels/next/next/include/linux/virtio_config.h:190 duplicate section name 'Return'
>>>>
>>>> Introduced by commit
>>>>
>>>>   bee8c7c24b73 ("virtio: introduce map ops in virtio core")
>>>>
>>>> but is probably a bug in our scripts as those lines above have "Returns:"
>>>> in them, not "Return:".  
>>>
>>> It is not a mistake. What happens is that, when kernel-doc detects
>>> something like:
>>>
>>> 	/**
>>> ...
>>> 	 * return: something
>>> ...
>>> 	 *    returns: else
>>> ...
>>> 	 */
>>>
>>> we have a duplicated section.  
>>
>> This seems like something we should be able to fix...will try to find
>> some time to look into it...
> 
> It is easy to fix, but it may break some things:
> 
> 
> 	$ git grep -l -E "\* \s+returns?:"
> 	drivers/edac/i5000_edac.c
> 	drivers/edac/i5400_edac.c
> 	drivers/gpu/drm/amd/display/dc/bios/command_table_helper2.c
> 	drivers/gpu/drm/ingenic/ingenic-ipu.c
> 	drivers/misc/sgi-gru/grufault.c
> 	drivers/net/wireless/marvell/libertas/cmd.c
> 	drivers/net/wireless/marvell/libertas/firmware.c
> 	drivers/net/wireless/marvell/libertas/if_usb.c
> 	drivers/net/wireless/marvell/libertas/main.c
> 	drivers/pci/rom.c
> 	drivers/scsi/qla2xxx/qla_edif.c
> 	drivers/tty/moxa.c
> 
> And this is only for "return" section. There are also other places
> where sections have more than one space. For instance, on 219
> files, we have:
> 
> 	$ git grep -l -E "\* \s+@\w+:"|wc -l
> 	219
> 
> like here:
> 
> 	drivers/ata/sata_mv.c-/**
> 	drivers/ata/sata_mv.c- *      mv_print_info - Dump key info to kernel log for perusal.
> 	drivers/ata/sata_mv.c: *      @host: ATA host to print info about
> 	drivers/ata/sata_mv.c- *
> 	drivers/ata/sata_mv.c- *      FIXME: complete this.

Yes, lots like that.

> 
> So, before changing the regex:
> 
> 	known_section_names = 'description|context|returns?|notes?|examples?'
> 	known_sections = KernRe(known_section_names, flags = re.I)
> 	doc_sect = doc_com + \
> -	    KernRe(r'\s*(@[.\w]+|@\.\.\.|' + known_section_names + r')\s*:([^:].*)?$',
> +	    KernRe(r'\s?(@[.\w]+|@\.\.\.|' + known_section_names + r')\s*:([^:].*)?$',
> 	           flags=re.I, cache=False)
> 
> to accept only a single space or no spaces, we need to change kernel-doc
> markups on lots of files.
> 
> Ok, an alternative would be to identify the indentation, but this could
> also be problematic.

We also need to be aware that the problem does not involve only
multiple "return:/returns:" lines. I.e., the ':' is not required.

Currently just having a kernel-doc comment like
 * this function could break the machine but instead it will just
 * return an error before doing that.

causes a warning.
Just run 'make mandocs &> mandocs.foo' and you can see lots of false
warnings.


-- 
~Randy

Re: linux-next: build warnings after merge of Linus' tree

[Randy Dunlap]

On 11/13/25 2:28 PM, Randy Dunlap wrote:
> 
> 
> On 11/13/25 2:01 PM, Mauro Carvalho Chehab wrote:
>> Em Thu, 13 Nov 2025 09:23:27 -0700
>> Jonathan Corbet <corbet@lwn.net> escreveu:
>>
>>> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
>>>
>>>> Em Thu, 13 Nov 2025 12:55:37 +1100
>>>> Stephen Rothwell <sfr@canb.auug.org.au> escreveu:
>>>>  
>>>>> Hi all,
>>>>>
>>>>> Today's linux-next build (htmldocs) produced these warnings:
>>>>>
>>>>> WARNING: /home/sfr/kernels/next/next/include/linux/virtio_config.h:174 duplicate section name 'Return'
>>>>> WARNING: /home/sfr/kernels/next/next/include/linux/virtio_config.h:184 duplicate section name 'Return'
>>>>> WARNING: /home/sfr/kernels/next/next/include/linux/virtio_config.h:190 duplicate section name 'Return'
>>>>>
>>>>> Introduced by commit
>>>>>
>>>>>   bee8c7c24b73 ("virtio: introduce map ops in virtio core")
>>>>>
>>>>> but is probably a bug in our scripts as those lines above have "Returns:"
>>>>> in them, not "Return:".  
>>>>
>>>> It is not a mistake. What happens is that, when kernel-doc detects
>>>> something like:
>>>>
>>>> 	/**
>>>> ...
>>>> 	 * return: something
>>>> ...
>>>> 	 *    returns: else
>>>> ...
>>>> 	 */
>>>>
>>>> we have a duplicated section.  
>>>
>>> This seems like something we should be able to fix...will try to find
>>> some time to look into it...
>>
>> It is easy to fix, but it may break some things:
>>
>>
>> 	$ git grep -l -E "\* \s+returns?:"
>> 	drivers/edac/i5000_edac.c
>> 	drivers/edac/i5400_edac.c
>> 	drivers/gpu/drm/amd/display/dc/bios/command_table_helper2.c
>> 	drivers/gpu/drm/ingenic/ingenic-ipu.c
>> 	drivers/misc/sgi-gru/grufault.c
>> 	drivers/net/wireless/marvell/libertas/cmd.c
>> 	drivers/net/wireless/marvell/libertas/firmware.c
>> 	drivers/net/wireless/marvell/libertas/if_usb.c
>> 	drivers/net/wireless/marvell/libertas/main.c
>> 	drivers/pci/rom.c
>> 	drivers/scsi/qla2xxx/qla_edif.c
>> 	drivers/tty/moxa.c
>>
>> And this is only for "return" section. There are also other places
>> where sections have more than one space. For instance, on 219
>> files, we have:
>>
>> 	$ git grep -l -E "\* \s+@\w+:"|wc -l
>> 	219
>>
>> like here:
>>
>> 	drivers/ata/sata_mv.c-/**
>> 	drivers/ata/sata_mv.c- *      mv_print_info - Dump key info to kernel log for perusal.
>> 	drivers/ata/sata_mv.c: *      @host: ATA host to print info about
>> 	drivers/ata/sata_mv.c- *
>> 	drivers/ata/sata_mv.c- *      FIXME: complete this.
> 
> Yes, lots like that.
> 
>>
>> So, before changing the regex:
>>
>> 	known_section_names = 'description|context|returns?|notes?|examples?'
>> 	known_sections = KernRe(known_section_names, flags = re.I)
>> 	doc_sect = doc_com + \
>> -	    KernRe(r'\s*(@[.\w]+|@\.\.\.|' + known_section_names + r')\s*:([^:].*)?$',
>> +	    KernRe(r'\s?(@[.\w]+|@\.\.\.|' + known_section_names + r')\s*:([^:].*)?$',
>> 	           flags=re.I, cache=False)
>>
>> to accept only a single space or no spaces, we need to change kernel-doc
>> markups on lots of files.
>>
>> Ok, an alternative would be to identify the indentation, but this could
>> also be problematic.
> 
> We also need to be aware that the problem does not involve only
> multiple "return:/returns:" lines. I.e., the ':' is not required.
> 
> Currently just having a kernel-doc comment like
>  * this function could break the machine but instead it will just
>  * return an error before doing that.
> 
> causes a warning.
> Just run 'make mandocs &> mandocs.foo' and you can see lots of false
> warnings.

Big OOPS! I ran 'make mandocs' on linux-next-20251112. If I use
linux-next-20251113, most of them are gone.  :)
Thanks.

-- 
~Randy