From 2f444efdaaed82f69d0afc4a7038a8563d8a3fa1 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 22 Jun 2020 16:31:21 -0600 Subject: docs: Don't push Sphinx upgrades quite so readily The sphinx-pre-install script will put out a verbose message recommending an upgrade for anybody running less than 2.4.4 - which was only released in March. So *everybody* will see that warning at this point. Let's only warn if the user is below our generally recommended version (1.7.9 currently). It might be good to put out a warning if people are explicitly making PDF files, but would need to be done in a different place and relatively few people do that. Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 4 ---- 1 file changed, 4 deletions(-) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index c680c3efb176..40fa6923e80a 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -323,10 +323,6 @@ sub check_sphinx() $rec_sphinx_upgrade = 1; return; } - if ($cur_version lt $min_pdf_version) { - $rec_sphinx_upgrade = 1; - return; - } # On version check mode, just assume Sphinx has all mandatory deps exit (0) if ($version_check); -- cgit v1.2.3-70-g09d2 From 3556108eb40a35836df1ef8228eca7ffa7dab764 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 23 Jun 2020 09:09:00 +0200 Subject: scripts/kernel-doc: parse __ETHTOOL_DECLARE_LINK_MODE_MASK The __ETHTOOL_DECLARE_LINK_MODE_MASK macro is a variant of DECLARE_BITMAP(), used by phylink.h. As we have already a parser for DECLARE_BITMAP(), let's add one for this macro, in order to avoid such warnings: ./include/linux/phylink.h:54: warning: Function parameter or member '__ETHTOOL_DECLARE_LINK_MODE_MASK(advertising' not described in 'phylink_link_state' ./include/linux/phylink.h:54: warning: Function parameter or member '__ETHTOOL_DECLARE_LINK_MODE_MASK(lp_advertising' not described in 'phylink_link_state' Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/d1d1dea67a28117c0b0c33271b139c4455fef287.1592895969.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 2 ++ 1 file changed, 2 insertions(+) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index b4c963f8364e..43b8312363a5 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1083,7 +1083,9 @@ sub dump_struct($$) { $members =~ s/\s*__packed\s*/ /gos; $members =~ s/\s*CRYPTO_MINALIGN_ATTR/ /gos; $members =~ s/\s*____cacheline_aligned_in_smp/ /gos; + # replace DECLARE_BITMAP + $members =~ s/__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)/DECLARE_BITMAP($1, __ETHTOOL_LINK_MODE_MASK_NBITS)/gos; $members =~ s/DECLARE_BITMAP\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos; # replace DECLARE_HASHTABLE $members =~ s/DECLARE_HASHTABLE\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[1 << (($2) - 1)\]/gos; -- cgit v1.2.3-70-g09d2 From 7ae281b05c0cebef4ef0643e74300fbe84760c3c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 23 Jun 2020 09:09:02 +0200 Subject: scripts/kernel-doc: handle function pointer prototypes There are some function pointer prototypes inside the net includes, like this one: int (*pcs_config)(struct phylink_config *config, unsigned int mode, phy_interface_t interface, const unsigned long *advertising); There's nothing wrong using it with kernel-doc, but we need to add a rule for it to parse such kind of prototype. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/fec520dd731a273013ae06b7653a19c7d15b9562.1592895969.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 43b8312363a5..e991d7f961e9 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1771,6 +1771,11 @@ sub process_proto_function($$) { $prototype =~ s@/\*.*?\*/@@gos; # strip comments. $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's. $prototype =~ s@^\s+@@gos; # strip leading spaces + + # Handle prototypes for function pointers like: + # int (*pcs_config)(struct foo) + $prototype =~ s@^(\S+\s+)\(\s*\*(\S+)\)@$1$2@gos; + if ($prototype =~ /SYSCALL_DEFINE/) { syscall_munge(); } -- cgit v1.2.3-70-g09d2 From 2c12c8103d8f15790cf880f1545dafa36acb004a Mon Sep 17 00:00:00 2001 From: Pierre-Louis Bossart Date: Tue, 28 Jul 2020 11:20:40 -0500 Subject: scripts/kernel-doc: optionally treat warnings as errors The kbuild bot recently added the W=1 option, which triggered documentation cleanups to squelch hundreds of kernel-doc warnings. To make sure new kernel contributions don't add regressions to kernel-doc descriptors, this patch suggests an option to treat warnings as errors in CI/automated tests. A -Werror command-line option is added to the kernel-doc script. When this option is set, the script will return the number of warnings found. The caller can then treat this positive return value as an error and stop the build. Using this command line option is however not straightforward when the kernel-doc script is called from other scripts. To align with typical kernel compilation or documentation generation, the Werror option is also set by checking the KCFLAGS environment variable, or if KDOC_WERROR is defined, as in the following examples: KCFLAGS="-Wall -Werror" make W=1 sound/ KCFLAGS="-Wall -Werror" make W=1 drivers/soundwire/ KDOC_WERROR=1 make htmldocs Note that in the last example the documentation build does not stop, only an additional log is provided. Credits to Randy Dunlap for suggesting the use of environment variables. Suggested-by: Randy Dunlap Signed-off-by: Pierre-Louis Bossart Link: https://lore.kernel.org/r/20200728162040.92467-1-pierre-louis.bossart@linux.intel.com Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index e991d7f961e9..d1b445665ad6 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -81,6 +81,7 @@ Output selection modifiers: Other parameters: -v Verbose output, more warnings and other information. -h Print this help. + -Werror Treat warnings as errors. EOF print $message; @@ -273,6 +274,7 @@ my $kernelversion; my $dohighlight = ""; my $verbose = 0; +my $Werror = 0; my $output_mode = "rst"; my $output_preformatted = 0; my $no_doc_sections = 0; @@ -319,6 +321,18 @@ if (defined($ENV{'KBUILD_VERBOSE'})) { $verbose = "$ENV{'KBUILD_VERBOSE'}"; } +if (defined($ENV{'KDOC_WERROR'})) { + $Werror = "$ENV{'KDOC_WERROR'}"; +} + +if (defined($ENV{'KCFLAGS'})) { + my $kcflags = "$ENV{'KCFLAGS'}"; + + if ($kcflags =~ /Werror/) { + $Werror = 1; + } +} + # Generated docbook code is inserted in a template at a point where # docbook v3.1 requires a non-zero sequence of RefEntry's; see: # https://www.oasis-open.org/docbook/documentation/reference/html/refentry.html @@ -433,6 +447,8 @@ while ($ARGV[0] =~ m/^--?(.*)/) { push(@export_file_list, $file); } elsif ($cmd eq "v") { $verbose = 1; + } elsif ($cmd eq "Werror") { + $Werror = 1; } elsif (($cmd eq "h") || ($cmd eq "help")) { usage(); } elsif ($cmd eq 'no-doc-sections') { @@ -2262,4 +2278,9 @@ if ($verbose && $warnings) { print STDERR "$warnings warnings\n"; } -exit($output_mode eq "none" ? 0 : $errors); +if ($Werror && $warnings) { + print STDERR "$warnings warnings as Errors\n"; + exit($warnings); +} else { + exit($output_mode eq "none" ? 0 : $errors) +} -- cgit v1.2.3-70-g09d2