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
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
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?
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
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.