[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 092/113] scripts/kernel-doc: optionally treat warnings as errors
From: |
Paolo Bonzini |
Subject: |
[PULL 092/113] scripts/kernel-doc: optionally treat warnings as errors |
Date: |
Wed, 2 Dec 2020 03:08:28 -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
- [PULL 079/113] vl: remove serial_max_hds, (continued)
- [PULL 079/113] vl: remove serial_max_hds, Paolo Bonzini, 2020/12/02
- [PULL 075/113] hmp: introduce cmd_available, Paolo Bonzini, 2020/12/02
- [PULL 077/113] vl: extract machine done notifiers, Paolo Bonzini, 2020/12/02
- [PULL 094/113] kernel-doc: add support for ____cacheline_aligned attribute, Paolo Bonzini, 2020/12/02
- [PULL 096/113] Revert "scripts/kerneldoc: For Sphinx 3 use c:macro for macros with arguments", Paolo Bonzini, 2020/12/02
- [PULL 083/113] kernel-doc: fix processing nested structs with attributes, Paolo Bonzini, 2020/12/02
- [PULL 082/113] docs: temporarily disable the kernel-doc extension, Paolo Bonzini, 2020/12/02
- [PULL 081/113] config-file: move -set implementation to vl.c, Paolo Bonzini, 2020/12/02
- [PULL 085/113] scripts/kernel-doc: Add support for named variable macro arguments, Paolo Bonzini, 2020/12/02
- [PULL 089/113] Replace HTTP links with HTTPS ones: documentation, Paolo Bonzini, 2020/12/02
- [PULL 092/113] scripts/kernel-doc: optionally treat warnings as errors,
Paolo Bonzini <=
- [PULL 095/113] scripts: kernel-doc: add support for typedef enum, Paolo Bonzini, 2020/12/02
- [PULL 097/113] Revert "kernel-doc: Use c:struct for Sphinx 3.0 and later", Paolo Bonzini, 2020/12/02
- [PULL 102/113] scripts: kernel-doc: fix typedef identification, Paolo Bonzini, 2020/12/02
- [PULL 098/113] scripts: kernel-doc: make it more compatible with Sphinx 3.x, Paolo Bonzini, 2020/12/02
- [PULL 107/113] Revert "kernel-doc: Handle function typedefs without asterisks", Paolo Bonzini, 2020/12/02
- [PULL 104/113] scripts: kernel-doc: allow passing desired Sphinx C domain dialect, Paolo Bonzini, 2020/12/02
- [PULL 078/113] vl: extract softmmu/rtc.c, Paolo Bonzini, 2020/12/02
- [PULL 093/113] kernel-doc: include line numbers for function prototypes, Paolo Bonzini, 2020/12/02
- [PULL 106/113] scripts: kernel-doc: try to use c:function if possible, Paolo Bonzini, 2020/12/02
- [PULL 105/113] scripts: kernel-doc: fix line number handling, Paolo Bonzini, 2020/12/02