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

From: Randy Dunlap <[email-masked]>
Date: Thu, 13 Nov 2025 14:42:48 -0800

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 <[email-masked]> escreveu:
>>
>>> Mauro Carvalho Chehab <[email-masked]> writes:
>>>
>>>> Em Thu, 13 Nov 2025 12:55:37 +1100
>>>> Stephen Rothwell <[email-masked]> 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