"WARNING: Duplicate C declaration" from recent Sphinx (was Re: [PATCH] docs: sphinx/requirements: Limit jinja2<3.1)

From: Akira Yokosawa <akiyks@gmail.com>
To: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: linux-doc@vger.kernel.org, Jonathan Corbet <corbet@lwn.net>,
	Akira Yokosawa <akiyks@gmail.com>
Subject: "WARNING: Duplicate C declaration" from recent Sphinx (was Re: [PATCH] docs: sphinx/requirements: Limit jinja2<3.1)
Date: Sat, 21 May 2022 16:58:45 +0900	[thread overview]
Message-ID: <564cbd05-8788-9223-1ecc-59e7fc41b46a@gmail.com> (raw)
In-Reply-To: <edf80179-4776-773d-0c4a-e75a1824bfba@gmail.com>

On Thu, 31 Mar 2022 23:32:41 +0900,
Akira Yokosawa wrote:
> On Wed, 30 Mar 2022 19:07:24 +0200,
> Mauro Carvalho Chehab wrote:
>> Em Wed, 30 Mar 2022 23:59:05 +0900
>> Akira Yokosawa <akiyks@gmail.com> escreveu:
>>
>>> Hi Mauro,
>>>
>>> On Wed, 30 Mar 2022 02:25:34 +0200,
>>> Mauro Carvalho Chehab wrote:
>>> [...]
>>>> We need to verify both PDF and html generation, though, as I remember
>>>> that some 4.x versions had/(have?) issues with the C domain and duplicate
>>>> symbols detection.  
>>>
>>> Can you elaborate on the issue you observed?
>>> In which document did you see it?
>>
>> Sorry, it was on Sphinx 3.x, although the most complete fix got
>> merged on 4.0, I guess. This patch is related to it:
>>
>> 	b34b86d7a418 ("docs: conf.py: fix c:function support with Sphinx 3.x")
>>
>> Basically, the Sphinx maintainer for the C domain rewrote the code,
>> causing all references generated by kernel-doc to be broken, and
>> almost all references at the media docs as well. Before the changes,
>> there were just one domain for C code references, used for functions,
>> structs, enums, etc. After the change, each one requires a different
>> tag. The kerneldoc script has gained support for Sphinx version when
>> such issue was addressed.
>>
>> Another consequence of such change is that you can't have more than
>> one "read()" function inside the entire Kernel. While this makes
>> sense on userspace, It doesn't at Kernelspace, as different subsystems
>> may handle read/write/ioctl/... syscalls on their particular ways.
>> So, building docs were causing warnings about duplicated symbols.
>>
>> There were some changes that went on 4.x to fix it, when 
>> ".. c:namespace::" got merged. I don't remember when it was added.
> 
> Thank you for the detailed explanation.
> 
> So I compared logs from "make SPHINXDIRS=driver-api htmldocs" with
> Sphinx 2.4.4 and 4.5.0 on current docs-next.
> 
> There are 8 more lines in the log from 4.5.0 than from 2.4.4, give
> or take minor format differences.
> 
> Here are those extra 8 lines (long lines are kept):
> 
> ----
> /wk/Documentation/driver-api/usb/usb.rst:967: WARNING: Duplicate C declaration, also defined at usb/gadget:775.
> Declaration is '.. c:struct:: usb_string'.
> /wk/Documentation/driver-api/miscellaneous:48: ./drivers/pwm/core.c:679: WARNING: Duplicate C declaration, also defined at miscellaneous:305.
> Declaration is '.. c:function:: int pwm_capture (struct pwm_device *pwm, struct pwm_capture *result, unsigned long timeout)'.
> /wk/Documentation/driver-api/surface_aggregator/client-api:25: ./drivers/platform/surface/aggregator/controller.c:1689: WARNING: Duplicate C declaration, also defined at surface_aggregator/client-api:105.
> Declaration is '.. c:function:: int ssam_request_sync (struct ssam_controller *ctrl, const struct ssam_request *spec, struct ssam_response *rsp)'.
> /wk/Documentation/driver-api/80211/mac80211:109: ./include/net/mac80211.h:4811: WARNING: Duplicate C declaration, also defined at 80211/mac80211:1024.
> Declaration is '.. c:function:: void ieee80211_tx_status (struct ieee80211_hw *hw, struct sk_buff *skb)'.
> ----
> 
> So those "WARNING: Duplicate C declaration" messages are what you
> mentioned earlier, aren't they?
> 

So, I think I have figured out what causes those "WARNING: Duplicate
C declaration".

When you have kernel-doc comments for both struct and function
of the same name, recent Sphinx emits this warning.

Although Sphinx versions 1.7.9 and 2.4.4 don't complain, the result
is the same with Sphinx 3.x and 4.x (with the fix to kernel-doc Mauro
mentioned above).

I have no idea which version of Sphinx is employed for building pages at
https://www.kernel.org/doc/html/latest/driver-api/80211/mac80211.html,
but the cross reference to the ieee80211_tx_status() function in the
description of ieee80211_rx_ni() points to struct ieee80211_tx_status,
which is not an expected behavior.

In this case, it seems to me that both the struct and function
kernel-doc comments are included by the kernel-doc directive

.. kernel-doc:: include/net/mac80211.h
   :functions:
	ieee80211_rx_status
        [...]

at Documentation/driver-api/80211/mac80211.rst:109.

As the :functions: option is identical to :identifiers:, both of
kernel-doc comments in mac80211.h, namely:

    include/net/mac80211.h:1148: * struct ieee80211_tx_status - extended tx status info for rate control

    include/net/mac80211.h:4813: * ieee80211_tx_status - transmit status callback

are extracted by the kerneldoc extension (or the kernel-doc script).

Mauro, does your earlier comment:
>> Another consequence of such change is that you can't have more than
>> one "read()" function inside the entire Kernel. 

apply to those struct and functions of the identical name?

I just want to know what is the expected behavior in this case.

Note: Line counts in this mail are those of v5.18-rc7.

        Thanks, Akira

[...]