* [PATCH] scripts/kernel-doc: optionally treat warnings as errors
@ 2020-07-24 23:01 Pierre-Louis Bossart
2020-07-27 22:28 ` Jonathan Corbet
0 siblings, 1 reply; 5+ messages in thread
From: Pierre-Louis Bossart @ 2020-07-24 23:01 UTC (permalink / raw)
To: linux-doc
Cc: Jonathan Corbet, linux-kernel, Pierre-Louis Bossart, Randy Dunlap
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 command-line option is
provided to the kernel-doc script, as well as a check on environment
variables to turn this optional behavior on.
Examples for the two subsystems I contribute to:
KCFLAGS="-Wall -Werror" make W=1 sound/
KCFLAGS="-Wall -Werror" make W=1 drivers/soundwire/
Randy Dunlap also suggested adding a log for when generating
documentation. The documentation build is however not stopped for now.
KDOC_WERROR=1 make htmldocs
Suggested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com>
---
scripts/kernel-doc | 23 ++++++++++++++++++++++-
1 file changed, 22 insertions(+), 1 deletion(-)
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)
+}
--
2.25.1
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH] scripts/kernel-doc: optionally treat warnings as errors
2020-07-24 23:01 [PATCH] scripts/kernel-doc: optionally treat warnings as errors Pierre-Louis Bossart
@ 2020-07-27 22:28 ` Jonathan Corbet
2020-07-27 23:09 ` Pierre-Louis Bossart
0 siblings, 1 reply; 5+ messages in thread
From: Jonathan Corbet @ 2020-07-27 22:28 UTC (permalink / raw)
To: Pierre-Louis Bossart; +Cc: linux-doc, linux-kernel, Randy Dunlap
On Fri, 24 Jul 2020 18:01:38 -0500
Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com> wrote:
> 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 command-line option is
> provided to the kernel-doc script, as well as a check on environment
> variables to turn this optional behavior on.
>
> Examples for the two subsystems I contribute to:
>
> KCFLAGS="-Wall -Werror" make W=1 sound/
> KCFLAGS="-Wall -Werror" make W=1 drivers/soundwire/
>
> Randy Dunlap also suggested adding a log for when generating
> documentation. The documentation build is however not stopped for now.
>
> KDOC_WERROR=1 make htmldocs
So I'm not opposed to this, but I'm missing a couple of things in the
changelog:
- A statement that you are adding a -Werror option that invokes this
behavior.
- Mention of the fact that you also cause it to look at a couple of
environment variables and change its behavior based on that.
Could I get a version with that clarified a bit?
Thanks,
jon
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] scripts/kernel-doc: optionally treat warnings as errors
2020-07-27 22:28 ` Jonathan Corbet
@ 2020-07-27 23:09 ` Pierre-Louis Bossart
2020-07-27 23:15 ` Jonathan Corbet
0 siblings, 1 reply; 5+ messages in thread
From: Pierre-Louis Bossart @ 2020-07-27 23:09 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Randy Dunlap
Thank Jon for the feedback,
>> 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 command-line option is
>> provided to the kernel-doc script, as well as a check on environment
>> variables to turn this optional behavior on.
>>
>> Examples for the two subsystems I contribute to:
>>
>> KCFLAGS="-Wall -Werror" make W=1 sound/
>> KCFLAGS="-Wall -Werror" make W=1 drivers/soundwire/
>>
>> Randy Dunlap also suggested adding a log for when generating
>> documentation. The documentation build is however not stopped for now.
>>
>> KDOC_WERROR=1 make htmldocs
>
> So I'm not opposed to this, but I'm missing a couple of things in the
> changelog:
>
> - A statement that you are adding a -Werror option that invokes this
> behavior.
>
> - Mention of the fact that you also cause it to look at a couple of
> environment variables and change its behavior based on that.
>
> Could I get a version with that clarified a bit?
Both points were covered by the sentence "A command-line option is
provided to the kernel-doc script, as well as a check on environment
variables to turn this optional behavior on".
I can try and make this clearer, maybe by moving this sentence to the
start of a new paragraph?
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] scripts/kernel-doc: optionally treat warnings as errors
2020-07-27 23:09 ` Pierre-Louis Bossart
@ 2020-07-27 23:15 ` Jonathan Corbet
2020-07-27 23:18 ` Pierre-Louis Bossart
0 siblings, 1 reply; 5+ messages in thread
From: Jonathan Corbet @ 2020-07-27 23:15 UTC (permalink / raw)
To: Pierre-Louis Bossart; +Cc: linux-doc, linux-kernel, Randy Dunlap
On Mon, 27 Jul 2020 18:09:21 -0500
Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com> wrote:
> Both points were covered by the sentence "A command-line option is
> provided to the kernel-doc script, as well as a check on environment
> variables to turn this optional behavior on".
Making that more prominent would be good, but a changelog like this should
say *which* command-line option was provided, and *which* environment
variables are checked. Don't make people go digging through the patch to
figure it out. See what I'm getting at?
Thanks,
jon
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] scripts/kernel-doc: optionally treat warnings as errors
2020-07-27 23:15 ` Jonathan Corbet
@ 2020-07-27 23:18 ` Pierre-Louis Bossart
0 siblings, 0 replies; 5+ messages in thread
From: Pierre-Louis Bossart @ 2020-07-27 23:18 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Randy Dunlap
On 7/27/20 6:15 PM, Jonathan Corbet wrote:
> On Mon, 27 Jul 2020 18:09:21 -0500
> Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com> wrote:
>
>> Both points were covered by the sentence "A command-line option is
>> provided to the kernel-doc script, as well as a check on environment
>> variables to turn this optional behavior on".
>
>
> Making that more prominent would be good, but a changelog like this should
> say *which* command-line option was provided, and *which* environment
> variables are checked. Don't make people go digging through the patch to
> figure it out. See what I'm getting at?
ok. I tried to avoid duplicating what's in the code, since it's
relatively minimal and self-explanatory but I see your point. Will send
a v2.
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2020-07-27 23:18 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-07-24 23:01 [PATCH] scripts/kernel-doc: optionally treat warnings as errors Pierre-Louis Bossart
2020-07-27 22:28 ` Jonathan Corbet
2020-07-27 23:09 ` Pierre-Louis Bossart
2020-07-27 23:15 ` Jonathan Corbet
2020-07-27 23:18 ` Pierre-Louis Bossart
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).