From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 7578DC433EF for ; Sat, 21 May 2022 09:46:37 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S235042AbiEUJqg (ORCPT ); Sat, 21 May 2022 05:46:36 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:52544 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234199AbiEUJqf (ORCPT ); Sat, 21 May 2022 05:46:35 -0400 Received: from dfw.source.kernel.org (dfw.source.kernel.org [IPv6:2604:1380:4641:c500::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 6452D2F006 for ; Sat, 21 May 2022 02:46:34 -0700 (PDT) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by dfw.source.kernel.org (Postfix) with ESMTPS id CC1FA6111C for ; Sat, 21 May 2022 09:46:33 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 567B9C385A5; Sat, 21 May 2022 09:46:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1653126393; bh=Ef1Ofi2vWDabAfToSsNeZYYiOyAqSxpfOsHsO55wis0=; h=Date:From:To:Cc:Subject:In-Reply-To:References:From; b=pZbmE3BmfYjgJ+ONqcsFdPbS2CWPOknm3sL+THZf8KCtcgG9DHZNClYvLBvE0kjY8 GRx+y7KwPMHdCFiqdpanZCPbofXe45L1NslLluatXWDUf6BqdNdzIrIUJbRFq3zZhq Tdne6fLd4rv8IGP6DdiJcGq8we/NNx5CDfPPkKOjtuo5ngczndRCivp5aII1+NRx1B OJw28yHaIhfSN6oFtPzuLwjGR9s1VM3fvHL3TzhFT1VTFk5Eg3tRGS/JuHqMq7Y+ic R0jdp06cIkoOBOURbnTjP+6qpDUEgX/9ZD9XJ/sYOrW4EnrG3klmUnYhjJ4F1dooUj 6y/Ox5Q0RSx6g== Date: Sat, 21 May 2022 11:46:29 +0200 From: Mauro Carvalho Chehab To: Akira Yokosawa Cc: linux-doc@vger.kernel.org, Jonathan Corbet Subject: Re: "WARNING: Duplicate C declaration" from recent Sphinx (was Re: [PATCH] docs: sphinx/requirements: Limit jinja2<3.1) Message-ID: <20220521114629.6ee9fc06@coco.lan> In-Reply-To: <564cbd05-8788-9223-1ecc-59e7fc41b46a@gmail.com> References: <7dbff8a0-f4ff-34a0-71c7-1987baf471f9@gmail.com> <871qyk7p28.fsf@meer.lwn.net> <20220330022534.10ac0a50@coco.lan> <20220330190724.1596e01a@coco.lan> <564cbd05-8788-9223-1ecc-59e7fc41b46a@gmail.com> X-Mailer: Claws Mail 4.1.0 (GTK 3.24.31; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Precedence: bulk List-ID: X-Mailing-List: linux-doc@vger.kernel.org Em Sat, 21 May 2022 16:58:45 +0900 Akira Yokosawa escreveu: > 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 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". Basically there are two places defining the same function. This could either be: 1. because the same header/c file is included on multiple places with kernel-doc directives; 2. because both *.c and *.h files declare the same function and both are included via kernel-doc directives; 3. because they use different namespaces; 4. because they're documenting system calls. For (1) and (2) the solution is to fix the kernel-doc includes and/or the header/c files; For (3) and (4) the solution is to define a c namespace via .. c:namespace:: foo meta-tags. > When you have kernel-doc comments for both struct and function > of the same name, recent Sphinx emits this warning. Yes. > > 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). True, it doesn't complain, but the generated documents have issues. > 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). The Kernel-doc extension should create two separate references for newer Kernels, depending on the version. With older versions of Sphinx, it generates: $ ./scripts/kernel-doc -sphinx-version 2.1 include/net/mac80211.h|grep "c:.*ieee80211_tx_status\b" .. c:type:: struct ieee80211_tx_status .. c:function:: void ieee80211_tx_status (struct ieee80211_hw *hw, struct sk_buff *skb) .. c:function:: void ieee80211_tx_status_ext (struct ieee80211_hw *hw, struct ieee80211_tx_status *status) Here, there's just a single namespace, so both function and type will be considered as the same thing. No warnings are generated, though. Versions 3.1 and above: $ ./scripts/kernel-doc -sphinx-version 3.1 include/net/mac80211.h|grep "c:.*ieee80211_tx_status\b" .. c:struct:: ieee80211_tx_status .. c:function:: void ieee80211_tx_status (struct ieee80211_hw *hw, struct sk_buff *skb) .. c:function:: void ieee80211_tx_status_ext (struct ieee80211_hw *hw, struct ieee80211_tx_status *status) This works since version 3.0, but only on version 4.0 namespace tags started to work. As far as I know: Sphinx < 3: there's a single namespace. It doesn't check duplicated refs. So, cross-references there will be plain broken on symbols with identical names. Sphinx 3.0: Although it uses different tags, there's still a single namespace. It will warn about duplicate symbols. Building docs with such version will generate lots of warnings that should not be fixed. This is a version that we don't support well. Sphinx 3.1 and above: structs, enums, functions, typedefs, etc have their own separate namespaces. So, it is possible to have struct with the same name as a function. Yet, it will complain about duplicated symbols for system calls. I guess we added a hack somethere to avoid too much noise on versions between 3.1 and 4.0. Sphinx 4.0 and above: it is now possible to add a namespace. This allows fixing things like read() system calls that have different meanings on different subsystems. On other words, only with Sphinx 4.0 and above, the cross-references for C domain symbols should all be OK. > > 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. Yes, that's the case for versions < 4.0. On 4.0, we need to specify a c namespace to document them. You can se such things if you do a: $ git grep c:namespace Documentation/userspace-api/ The media uAPI documentation has separate documentation for syscalls, depending on being CEC, V4L or one of the DVB APIs. Thanks, Mauro