There are some new warnings when building the documentation from
yesterday's linux next. This small series fix them.
- patch 1 documents two new kernel-doc parameters on a net core file.
I used the commit log in order to help documenting them;
- patch 2 fixes some tags at UMLv2 howto;
- patches 3 and 5 add some new documents at the corresponding
index file.
- patch 4 changes kernel-doc script for it to recognize typedef enums.
Patch 4 should probably be merged via docs tree, but the others
are against stuff recently added at linux-next. So, the better is to
merge them directly at the trees which introduced the issue.
-
As a reference, the patches fixing all html build warnings are at:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=sphinx3-fixes-v3
Such series also adds support for Sphinx versions 3.1 and above.
It should be noticed that, with Sphinx version 3 and above, there
are a few new warnings, because currently Sphinx assumes a
that names are unique for all C symbols. There are a few cases
where we have the same name for a function and for a struct at
the Kernel. Upstream is already working on a solution for that.
So, for now, I recomend doing html builds with version < 3.
Mauro Carvalho Chehab (6):
net: core: document two new elements of struct net_device
docs: vcpu.rst: fix some build warnings
docs: virt: user_mode_linux_howto_v2.rst: fix a literal block markup
docs: i2c: index.rst: add slave-testunit-backend.rst
scripts: kernel-doc: add support for typedef enum
docs: gpio: add a new document to its index.rst
Documentation/admin-guide/gpio/index.rst | 1 +
.../admin-guide/hw-vuln/l1d_flush.rst | 3 +--
Documentation/i2c/index.rst | 1 +
Documentation/virt/kvm/devices/vcpu.rst | 26 +++++++++----------
.../virt/uml/user_mode_linux_howto_v2.rst | 1 +
include/linux/netdevice.h | 5 ++++
scripts/kernel-doc | 15 ++++++++---
7 files changed, 33 insertions(+), 19 deletions(-)
--
2.26.2
The PHY kernel-doc markup has gained support for documenting
a typedef enum.
However, right now the parser was not prepared for it.
So, add support for parsing it.
Fixes: 4069a572d423 ("net: phy: Document core PHY structures")
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
scripts/kernel-doc | 15 +++++++++++----
1 file changed, 11 insertions(+), 4 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index d94e28fcead0..5ac3749905e5 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1339,14 +1339,22 @@ sub show_warnings($$) {
sub dump_enum($$) {
my $x = shift;
my $file = shift;
+ my $members;
+
$x =~ s@/\*.*?\*/@@gos; # strip comments.
# strip #define macros inside enums
$x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
- if ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) {
+ if ($x =~ /typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;/) {
+ $declaration_name = $2;
+ $members = $1;
+ } elsif ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) {
$declaration_name = $1;
- my $members = $2;
+ $members = $2;
+ }
+
+ if ($declaration_name) {
my %_members;
$members =~ s/\s+$//;
@@ -1381,8 +1389,7 @@ sub dump_enum($$) {
'sections' => \%sections,
'purpose' => $declaration_purpose
});
- }
- else {
+ } else {
print STDERR "${file}:$.: error: Cannot parse enum!\n";
++$errors;
}
--
2.26.2
As warned by "make htmldocs", there are two new struct elements
that aren't documented:
../include/linux/netdevice.h:2159: warning: Function parameter or member 'unlink_list' not described in 'net_device'
../include/linux/netdevice.h:2159: warning: Function parameter or member 'nested_level' not described in 'net_device'
Fixes: 1fc70edb7d7b ("net: core: add nested_level variable in net_device")
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
include/linux/netdevice.h | 5 +++++
1 file changed, 5 insertions(+)
diff --git a/include/linux/netdevice.h b/include/linux/netdevice.h
index 78880047907e..7852921480da 100644
--- a/include/linux/netdevice.h
+++ b/include/linux/netdevice.h
@@ -1843,6 +1843,11 @@ enum netdev_priv_flags {
* @udp_tunnel_nic: UDP tunnel offload state
* @xdp_state: stores info on attached XDP BPF programs
*
+ * @nested_level: Used as as a parameter of spin_lock_nested() of
+ * dev->addr_list_lock.
+ * @unlink_list: As netif_addr_lock() can be called recursively,
+ * keep a list of interfaces to be deleted.
+ *
* FIXME: cleanup struct net_device such that network protocol info
* moves out.
*/
--
2.26.2
There's now a new ReST file. Add it to the index.rst file.
Fixes: ce7a2f77f976 ("docs: gpio: Add GPIO Aggregator documentation")
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/admin-guide/gpio/index.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/Documentation/admin-guide/gpio/index.rst b/Documentation/admin-guide/gpio/index.rst
index ef2838638e96..7db367572f30 100644
--- a/Documentation/admin-guide/gpio/index.rst
+++ b/Documentation/admin-guide/gpio/index.rst
@@ -9,6 +9,7 @@ gpio
gpio-aggregator
sysfs
+ gpio-mockup
.. only:: subproject and html
--
2.26.2
On Fri, 2 Oct 2020 07:49:44 +0200, Mauro Carvalho Chehab wrote:
> There are some new warnings when building the documentation from
> yesterday's linux next. This small series fix them.
>
> - patch 1 documents two new kernel-doc parameters on a net core file.
> I used the commit log in order to help documenting them;
> - patch 2 fixes some tags at UMLv2 howto;
> - patches 3 and 5 add some new documents at the corresponding
> index file.
> - patch 4 changes kernel-doc script for it to recognize typedef enums.
>
> [...]
Applied to next, thanks!
[2/6] KVM: arm64: Fix some documentation build warnings
commit: 030bdf3698b7c3af190dd1fe714f0545f23441d0
Cheers,
M.
--
Without deviation from the norm, progress is not possible.
On Fri, Oct 02, 2020 at 07:49:49AM +0200, Mauro Carvalho Chehab wrote:
> The PHY kernel-doc markup has gained support for documenting
> a typedef enum.
>
> However, right now the parser was not prepared for it.
Hi Mauro
Thanks for this. I'm using Sphinx 3.2.1, since that is what my Debian
box has. So it can be hard to see the new warnings amongst the old.
Will this patch get merged via Jonathan Corbet's tree?
Thanks
Andrew
On Fri, Oct 2, 2020 at 7:49 AM Mauro Carvalho Chehab
<[email protected]> wrote:
>
> There's now a new ReST file. Add it to the index.rst file.
>
> Fixes: ce7a2f77f976 ("docs: gpio: Add GPIO Aggregator documentation")
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
> Documentation/admin-guide/gpio/index.rst | 1 +
> 1 file changed, 1 insertion(+)
>
> diff --git a/Documentation/admin-guide/gpio/index.rst b/Documentation/admin-guide/gpio/index.rst
> index ef2838638e96..7db367572f30 100644
> --- a/Documentation/admin-guide/gpio/index.rst
> +++ b/Documentation/admin-guide/gpio/index.rst
> @@ -9,6 +9,7 @@ gpio
>
> gpio-aggregator
> sysfs
> + gpio-mockup
>
> .. only:: subproject and html
>
> --
> 2.26.2
>
Good catch, thanks!
Acked-by: Bartosz Golaszewski <[email protected]>
From: Mauro Carvalho Chehab <[email protected]>
Date: Fri, 2 Oct 2020 07:49:45 +0200
> As warned by "make htmldocs", there are two new struct elements
> that aren't documented:
>
> ../include/linux/netdevice.h:2159: warning: Function parameter or member 'unlink_list' not described in 'net_device'
> ../include/linux/netdevice.h:2159: warning: Function parameter or member 'nested_level' not described in 'net_device'
>
> Fixes: 1fc70edb7d7b ("net: core: add nested_level variable in net_device")
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Applied, thank you.
On Fri, Oct 02, 2020 at 07:49:50AM +0200, Mauro Carvalho Chehab wrote:
> There's now a new ReST file. Add it to the index.rst file.
>
> Fixes: ce7a2f77f976 ("docs: gpio: Add GPIO Aggregator documentation")
Shouldn't that be:
Fixes: fd1abe99e5fb ("Documentation: gpio: add documentation for gpio-mockup")
Cheers,
Kent.
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
> Documentation/admin-guide/gpio/index.rst | 1 +
> 1 file changed, 1 insertion(+)
>
> diff --git a/Documentation/admin-guide/gpio/index.rst b/Documentation/admin-guide/gpio/index.rst
> index ef2838638e96..7db367572f30 100644
> --- a/Documentation/admin-guide/gpio/index.rst
> +++ b/Documentation/admin-guide/gpio/index.rst
> @@ -9,6 +9,7 @@ gpio
>
> gpio-aggregator
> sysfs
> + gpio-mockup
>
> .. only:: subproject and html
>
> --
> 2.26.2
>
Hi Andrew,
Em Fri, 2 Oct 2020 14:07:28 +0200
Andrew Lunn <[email protected]> escreveu:
> On Fri, Oct 02, 2020 at 07:49:49AM +0200, Mauro Carvalho Chehab wrote:
> > The PHY kernel-doc markup has gained support for documenting
> > a typedef enum.
> >
> > However, right now the parser was not prepared for it.
>
> Hi Mauro
>
> Thanks for this. I'm using Sphinx 3.2.1, since that is what my Debian
> box has. So it can be hard to see the new warnings amongst the old.
Yeah, there were simply too much warnings with docs, and 3.2.1 is
even worse.
Things will improve a lot after merging my set of patches fixing
the issues for it. Yet, there are some warnings that can't currently
be fixed on Sphinx 3.2 (~10 warnings). Fixing those will require
some internal changes in Sphinx itself.
So, except if you need Sphinx 3 for some reason, I would suggest you
to uninstall it, and then use venv with Sphinx 2.4.4. The Kernel build
system should be able to provide you the commands for installing it,
once you remove the one from your PATH.
> Will this patch get merged via Jonathan Corbet's tree?
Yes, that's the plan.
Thanks,
Mauro
On Fri, Oct 2, 2020 at 7:49 AM Mauro Carvalho Chehab
<[email protected]> wrote:
> There's now a new ReST file. Add it to the index.rst file.
>
> Fixes: ce7a2f77f976 ("docs: gpio: Add GPIO Aggregator documentation")
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
This patch (6/6) applied to the GPIO tree.
Fixed the Fixes: as indicated by Kent.
Yours,
Linus Walleij