[PATCH] kernel-doc: add a warning prefix option

[PATCH] kernel-doc: add a warning prefix option

[Randy Dunlap]

Add an environment variable ("KDOC_LABEL") for use by scripts/kernel-doc.
This variable instructs kernel-doc to label each "warning:" line with
a prefix of the KDOC_LABEL value. E.g., using
  KDOC_LABEL="doc" ./scripts/kernel-doc -none -Wall kernel/panic.c
causes kernel-doc warnings to be emitted as "doc warning:", like this:
  kernel/panic.c:497: doc warning: No description found for return value of 'print_tainted'

This can aid either in finding or eliminating kernel-doc warnings.
'sparse' does something similar to this, although it uses a command line
option (-fdiagnostic-prefix[=prefix]).

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
---
 scripts/kernel-doc |   15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff -- a/scripts/kernel-doc b/scripts/kernel-doc
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -127,6 +127,7 @@ if ($#ARGV == -1) {
 }
 
 my $kernelversion;
+my $line_label;
 my ($sphinx_major, $sphinx_minor, $sphinx_patch);
 
 my $dohighlight = "";
@@ -439,6 +440,16 @@ sub get_kernel_version() {
     return $version;
 }
 
+# get line label from env
+sub get_line_label() {
+    my $label = '';
+
+    if (defined($ENV{'KDOC_LABEL'})) {
+	$label = $ENV{'KDOC_LABEL'} . " ";
+    }
+    return $label;
+}
+
 #
 sub print_lineno {
     my $lineno = shift;
@@ -450,7 +461,7 @@ sub print_lineno {
 sub emit_warning {
     my $location = shift;
     my $msg = shift;
-    print STDERR "$location: warning: $msg";
+    print STDERR "$location: ${line_label}warning: $msg";
     ++$warnings;
 }
 ##
@@ -2360,6 +2371,8 @@ if ($output_mode eq "rst") {
 
 $kernelversion = get_kernel_version();
 
+$line_label = get_line_label();
+
 # generate a sequence of code that will splice in highlighting information
 # using the s// operator.
 for (my $k = 0; $k < @highlights; $k++) {

Re: [PATCH] kernel-doc: add a warning prefix option

[Matthew Wilcox]

On Mon, Sep 18, 2023 at 07:34:15PM -0700, Randy Dunlap wrote:
> Add an environment variable ("KDOC_LABEL") for use by scripts/kernel-doc.
> This variable instructs kernel-doc to label each "warning:" line with
> a prefix of the KDOC_LABEL value. E.g., using
>   KDOC_LABEL="doc" ./scripts/kernel-doc -none -Wall kernel/panic.c
> causes kernel-doc warnings to be emitted as "doc warning:", like this:
>   kernel/panic.c:497: doc warning: No description found for return value of 'print_tainted'
> 
> This can aid either in finding or eliminating kernel-doc warnings.

I worry this will lead to people saying "Oh, it's just a doc warning,
so I ignored it".

Re: [PATCH] kernel-doc: add a warning prefix option

[Randy Dunlap]

On 9/18/23 21:08, Matthew Wilcox wrote:
> On Mon, Sep 18, 2023 at 07:34:15PM -0700, Randy Dunlap wrote:
>> Add an environment variable ("KDOC_LABEL") for use by scripts/kernel-doc.
>> This variable instructs kernel-doc to label each "warning:" line with
>> a prefix of the KDOC_LABEL value. E.g., using
>>   KDOC_LABEL="doc" ./scripts/kernel-doc -none -Wall kernel/panic.c
>> causes kernel-doc warnings to be emitted as "doc warning:", like this:
>>   kernel/panic.c:497: doc warning: No description found for return value of 'print_tainted'
>>
>> This can aid either in finding or eliminating kernel-doc warnings.
> 
> I worry this will lead to people saying "Oh, it's just a doc warning,
> so I ignored it".

Yeah, that's a fair comment.

I'll find some other way to do what I want to do.

Thanks.
-- 
~Randy