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
next prev parent reply other threads:[~2022-07-02 10:52 UTC|newest]
Thread overview: 40+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-06-17 20:57 [TECH TOPIC] What kernel documentation could be Jonathan Corbet
2022-06-17 20:57 ` [Ksummit-discuss] " Jonathan Corbet
2022-06-17 21:48 ` Laurent Pinchart
2022-06-17 21:48 ` Laurent Pinchart
2022-06-27 15:18 ` Jonathan Corbet
2022-06-18 8:24 ` Mauro Carvalho Chehab
2022-06-18 8:24 ` Mauro Carvalho Chehab
2022-06-18 11:03 ` Miguel Ojeda
2022-06-18 11:16 ` Mauro Carvalho Chehab
2022-06-18 11:16 ` Mauro Carvalho Chehab
2022-06-18 14:37 ` Miguel Ojeda
2022-06-23 9:18 ` Jani Nikula
2022-06-23 9:57 ` Mauro Carvalho Chehab
2022-06-23 10:30 ` Jani Nikula
2022-06-23 13:40 ` Jonathan Corbet
2022-06-24 7:33 ` Mauro Carvalho Chehab
2022-06-24 16:37 ` Markus Heiser
2022-06-27 15:27 ` Jonathan Corbet
2022-06-27 15:31 ` Christoph Hellwig
2022-06-28 7:43 ` Mauro Carvalho Chehab
2022-06-28 7:57 ` Geert Uytterhoeven
2022-06-28 11:01 ` Mauro Carvalho Chehab
2022-07-02 12:43 ` Stephen Rothwell
2022-06-24 22:57 ` Jonathan Corbet
2022-06-25 9:10 ` Mauro Carvalho Chehab
2022-06-25 14:00 ` Jonathan Corbet
2022-06-25 18:11 ` Linus Torvalds
2022-06-26 7:55 ` Mauro Carvalho Chehab
2022-06-26 9:26 ` Mauro Carvalho Chehab
2022-06-26 9:53 ` Mauro Carvalho Chehab
2022-06-27 15:28 ` Liam Howlett
2022-06-27 15:54 ` Christian Brauner
2022-06-27 16:27 ` Mark Brown
2022-06-28 10:53 ` Mauro Carvalho Chehab
2022-06-28 16:13 ` Luck, Tony
2022-06-27 15:34 ` Jonathan Corbet
2022-06-27 17:07 ` Linus Torvalds
2022-07-02 10:52 ` Mauro Carvalho Chehab [this message]
2022-06-25 17:43 ` Steven Rostedt
2022-06-25 17:48 ` Laurent Pinchart
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20220702115252.3953d316@sal.lan \
--to=mchehab@kernel.org \
--cc=corbet@lwn.net \
--cc=jani.nikula@intel.com \
--cc=ksummit-discuss@lists.linuxfoundation.org \
--cc=ksummit@lists.linux.dev \
--cc=markus.heiser@darmarit.de \
--cc=torvalds@linux-foundation.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).