[PATCH] scripts/kernel-doc: optionally treat warnings as errors

[PATCH] scripts/kernel-doc: optionally treat warnings as errors

[Pierre-Louis Bossart]

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

Re: [PATCH] scripts/kernel-doc: optionally treat warnings as errors

[Jonathan Corbet]

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

Re: [PATCH] scripts/kernel-doc: optionally treat warnings as errors

[Pierre-Louis Bossart]

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?

Re: [PATCH] scripts/kernel-doc: optionally treat warnings as errors

[Jonathan Corbet]

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

Re: [PATCH] scripts/kernel-doc: optionally treat warnings as errors

[Pierre-Louis Bossart]

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.