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@xxxxxxx> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> writes:
> 
> > Em Thu, 13 Nov 2025 12:55:37 +1100
> > Stephen Rothwell <sfr@xxxxxxxxxxxxxxxx> 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