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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

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