Re: [Ksummit-discuss] [TECH TOPIC] What kernel documentation could be

From: Mauro Carvalho Chehab <mchehab@kernel.org>
To: Linus Torvalds <torvalds@linux-foundation.org>
Cc: Jonathan Corbet <corbet@lwn.net>,
	Jani Nikula <jani.nikula@intel.com>,
	ksummit <ksummit-discuss@lists.linuxfoundation.org>,
	ksummit@lists.linux.dev,
	Markus Heiser <markus.heiser@darmarit.de>
Subject: Re: [Ksummit-discuss] [TECH TOPIC] What kernel documentation could be
Date: Sat, 2 Jul 2022 11:52:52 +0100	[thread overview]
Message-ID: <20220702115252.3953d316@sal.lan> (raw)
In-Reply-To: <CAHk-=wi-NnjCMTd5aC_WLfXN02gCXFOm0dbvSPaDYDkiByfrEg@mail.gmail.com>

Em Sat, 25 Jun 2022 11:11:40 -0700
Linus Torvalds <torvalds@linux-foundation.org> escreveu:

> On Sat, Jun 25, 2022 at 7:00 AM Jonathan Corbet <corbet@lwn.net> wrote:
> >
> > I said "some" - this was a proof-of-concept hack.  The complexity of
> > their symbol lookup code is ... daunting ... and not something that gets
> > fixed in one place.  More research is required...  
> 
> Note that at least for me, the issue with building docs isn't hugely
> performance related.
> 
> Yes, yes, it would be good if it was faster. But..
> 
> The primary problems I see with building the docs (and thus checking
> them, the same way I do an allmodconfig build test) is
> 
>  (a) it's insanely noisy, which makes and "check that it's ok" ENTIRELY USELESS.

I solved almost all warnings that can be fixed against -next.
Sending patches today.

However, there is an special case where warnings will be hit for perfectly
fine code, when docs are built with Sphinx 3.0 and upper:

	Documentation/driver-api/usb/usb:164: ./drivers/usb/core/message.c:967: WARNING: Duplicate C declaration, also defined at driver-api/usb/gadget:783.
	Declaration is '.. c:function:: int usb_string (struct usb_device *dev, int index, char *buf, size_t size)'.
	Documentation/driver-api/usb/usb.rst:967: WARNING: Duplicate C declaration, also defined at driver-api/usb/gadget:783.
	Declaration is '.. c:struct:: usb_string'.

In this specific case, there are both a struct and a function named 
"usb_string". So, the above is not an issue. While this is not fixed,
there will be a 22 lines noise (11 two-line warnings) after my fixes[1].

The root cause is that Sphinx has a single namespace for symbols, no matter
if the symbol is a function, a struct, an enum, etc. So, when the same
name is declared on multiple places, like in the case of "usb_string",
the cross-references will either point to the function or to the struct.
While this is annoying, it is usually not a big deal, as they are
typically placed at the same rst file.

While this problem affects *all* Sphinx versions so far, Sphinx 2.x.x 
doesn't warn when this happen, but newer versions complain about that. 
This is a well known issue and there are patches fixing it since 
Sphinx 3.1:

	https://github.com/sphinx-doc/sphinx/pull/8313

Those patches were expected to be merged on Sphinx 3.3, but ended
not being merged so far, as applying them would break support for
a Sphinx extension that it is used on several places.

---

[1] I got one case where the warning was actually reporting an issue:

	Documentation/driver-api/hte/tegra194-hte:28: ./drivers/gpio/gpiolib.c:2464: WARNING: Duplicate C declaration, also defined at driver-api>
	Declaration is '.. c:function:: int gpiod_enable_hw_timestamp_ns (struct gpio_desc *desc, unsigned long flags)'.
	Documentation/driver-api/hte/tegra194-hte.rst:2464: WARNING: Duplicate C declaration, also defined at driver-api/gpio/index:2464.
	Declaration is '.. c:function:: int gpiod_enable_hw_timestamp_ns(struct gpio_desc *desc, unsigned long flags)'.

Basically drivers/gpio/gpiolib.c is included twice for the same
symbols, one at Documentation/driver-api/gpio/index.rst, and then 
Documentation/driver-api/hte/tegra194-hte.rst includes it again for 
gpiod_enable_hw_timestamp_ns() and gpiod_disable_hw_timestamp_ns().

Regards,
Mauro