aboutsummaryrefslogtreecommitdiff
path: root/scripts/kernel-doc
diff options
context:
space:
mode:
authorPierre-Louis Bossart <pierre-louis.bossart@linux.intel.com>2020-11-17 17:52:53 +0100
committerPaolo Bonzini <pbonzini@redhat.com>2020-12-10 12:15:21 -0500
commit86cba21743bed485a9474696afb5dbb3d3372ea1 (patch)
tree958823b547e599ed38fb6f8f2227ee7fdbe58672 /scripts/kernel-doc
parent2552f59a348f5fc9df7af8175c20a195a1d93c4b (diff)
downloadqemu-86cba21743bed485a9474696afb5dbb3d3372ea1.zip
qemu-86cba21743bed485a9474696afb5dbb3d3372ea1.tar.gz
qemu-86cba21743bed485a9474696afb5dbb3d3372ea1.tar.bz2
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 <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>
Diffstat (limited to 'scripts/kernel-doc')
-rwxr-xr-xscripts/kernel-doc23
1 files changed, 22 insertions, 1 deletions
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 1cdece2..eb635eb 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)
+}