[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH v2 11/32] scripts/kernel-doc: optionally treat warnings as errors
From: |
Paolo Bonzini |
Subject: |
[PATCH v2 11/32] scripts/kernel-doc: optionally treat warnings as errors |
Date: |
Tue, 1 Dec 2020 05:34:41 -0500 |
From: Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com>
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 <rdunlap@infradead.org>
Signed-off-by: Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com>
Link:
https://lore.kernel.org/r/20200728162040.92467-1-pierre-louis.bossart@linux.intel.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Message-Id: <20201117165312.118257-11-pbonzini@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---
scripts/kernel-doc | 23 ++++++++++++++++++++++-
1 file changed, 22 insertions(+), 1 deletion(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 1cdece23fb..eb635eb94c 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -83,6 +83,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;
@@ -275,6 +276,7 @@ my $kernelversion;
my $dohighlight = "";
my $verbose = 0;
+my $Werror = 0;
my $output_mode = "rst";
my $output_preformatted = 0;
my $no_doc_sections = 0;
@@ -322,6 +324,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
@@ -436,6 +450,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') {
@@ -2292,4 +2308,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)
+}
--
2.26.2
- [PATCH v2 03/32] kernel-doc: add support for ____cacheline_aligned_in_smp attribute, (continued)
- [PATCH v2 03/32] kernel-doc: add support for ____cacheline_aligned_in_smp attribute, Paolo Bonzini, 2020/12/01
- [PATCH v2 05/32] scripts: kernel-doc: proper handle @foo->bar(), Paolo Bonzini, 2020/12/01
- [PATCH v2 06/32] scripts: kernel-doc: accept negation like !@var, Paolo Bonzini, 2020/12/01
- [PATCH v2 04/32] scripts/kernel-doc: Add support for named variable macro arguments, Paolo Bonzini, 2020/12/01
- [PATCH v2 09/32] scripts/kernel-doc: parse __ETHTOOL_DECLARE_LINK_MODE_MASK, Paolo Bonzini, 2020/12/01
- [PATCH v2 08/32] Replace HTTP links with HTTPS ones: documentation, Paolo Bonzini, 2020/12/01
- [PATCH v2 14/32] scripts: kernel-doc: add support for typedef enum, Paolo Bonzini, 2020/12/01
- [PATCH v2 07/32] scripts: kernel-doc: accept blank lines on parameter description, Paolo Bonzini, 2020/12/01
- [PATCH v2 15/32] Revert "scripts/kerneldoc: For Sphinx 3 use c:macro for macros with arguments", Paolo Bonzini, 2020/12/01
- [PATCH v2 10/32] scripts/kernel-doc: handle function pointer prototypes, Paolo Bonzini, 2020/12/01
- [PATCH v2 11/32] scripts/kernel-doc: optionally treat warnings as errors,
Paolo Bonzini <=
- [PATCH v2 02/32] kernel-doc: fix processing nested structs with attributes, Paolo Bonzini, 2020/12/01
- [PATCH v2 16/32] Revert "kernel-doc: Use c:struct for Sphinx 3.0 and later", Paolo Bonzini, 2020/12/01
- [PATCH v2 26/32] Revert "kernel-doc: Handle function typedefs without asterisks", Paolo Bonzini, 2020/12/01
- [PATCH v2 19/32] scripts: kernel-doc: fix troubles with line counts, Paolo Bonzini, 2020/12/01
- [PATCH v2 20/32] scripts: kernel-doc: reimplement -nofunction argument, Paolo Bonzini, 2020/12/01
- [PATCH v2 25/32] scripts: kernel-doc: try to use c:function if possible, Paolo Bonzini, 2020/12/01
- [PATCH v2 12/32] kernel-doc: include line numbers for function prototypes, Paolo Bonzini, 2020/12/01
- [PATCH v2 29/32] scripts: kernel-doc: split typedef complex regex, Paolo Bonzini, 2020/12/01
- [PATCH v2 13/32] kernel-doc: add support for ____cacheline_aligned attribute, Paolo Bonzini, 2020/12/01
- [PATCH v2 24/32] scripts: kernel-doc: fix line number handling, Paolo Bonzini, 2020/12/01