Skip to contentSkip to conversation

scripts: kernel-doc: Always increment warnings counter

PATCH Applied Niklas Söderlund 2 participants 2 messages Jun 13, 2022 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/1 scripts: kernel-doc: Always increment warnings counter

Some warnings do not increment the warnings counter making the behavior of running kernel-doc with -Werror unlogical as some warnings will be generated but not treated as errors.

Fix this by creating a helper function that always incrementing the warnings counter every time a warning is emitted. There is one location in get_sphinx_version() where a warning is not touched as it concerns the execution environment of the kernel-doc and not the documentation being processed.

Incrementing the counter only have effect when running kernel-doc in either verbose mode (-v or environment variable KBUILD_VERBOSE) or when treating warnings as errors (-Werror or environment variable KDOC_WERROR). In both cases the number of warnings printed is printed to stderr and for the later the exit code of kernel-doc is non-zero if warnings where encountered.

Simple test case to demo one of the warnings,

    $ cat test.c
    /**
     * foo() - Description
     */
    int bar();

# Without this change
$ ./scripts/kernel-doc -Werror -none test.c
test.c:4: warning: expecting prototype for foo(). Prototype was for bar() instead

# With this change
$ ./scripts/kernel-doc -Werror -none test.c
test.c:4: warning: expecting prototype for foo(). Prototype was for bar() instead
1 warnings as Errors

---
* Changes since v1
- Added a helper emit_warning() to print the message and increment the counter instead of adding statements to increment the counter where it was missing.
- My Perl is not the best but I have tested the change against all warnings but the 'suspicious ending line' warning and there is no change in output format.

---
 scripts/kernel-doc | 82 ++++++++++++++++++++--------------------------
 1 file changed, 35 insertions(+), 47 deletions(-)
scripts/kernel-doc +35 -47
index 7516949bb049e39f..aea04365bc69d386 100755
@@ -427,6 +427,13 @@ sub print_lineno {
         print ".. LINENO " . $lineno . "\n";
     }
 }
+
+sub emit_warning {
+    my $location = shift;
+    my $msg = shift;
+    print STDERR "$location: warning: $msg";
+    ++$warnings;
+}
 ##
 # dumps section contents to arrays/hashes intended for that purpose.
 #
@@ -451,8 +458,7 @@ sub dump_section {
 	if (defined($sections{$name}) && ($sections{$name} ne "")) {
 	    # Only warn on user specified duplicate section names.
 	    if ($name ne $section_default) {
-		print STDERR "${file}:$.: warning: duplicate section name '$name'\n";
-		++$warnings;
+		emit_warning("${file}:$.", "duplicate section name '$name'\n");
 	    }
 	    $sections{$name} .= $contents;
 	} else {
@@ -1094,7 +1100,7 @@ sub dump_struct($$) {
 
     if ($members) {
 	if ($identifier ne $declaration_name) {
-	    print STDERR "${file}:$.: warning: expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n";
+	    emit_warning("${file}:$.", "expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n");
 	    return;
 	}
 
@@ -1298,9 +1304,9 @@ sub dump_enum($$) {
     if ($members) {
 	if ($identifier ne $declaration_name) {
 	    if ($identifier eq "") {
-		print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n";
+		emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n");
 	    } else {
-		print STDERR "${file}:$.: warning: expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n";
+		emit_warning("${file}:$.", "expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n");
 	    }
 	    return;
 	}
@@ -1316,7 +1322,7 @@ sub dump_enum($$) {
 	    if (!$parameterdescs{$arg}) {
 		$parameterdescs{$arg} = $undescribed;
 	        if (show_warnings("enum", $declaration_name)) {
-			print STDERR "${file}:$.: warning: Enum value '$arg' not described in enum '$declaration_name'\n";
+			emit_warning("${file}:$.", "Enum value '$arg' not described in enum '$declaration_name'\n");
 		}
 	    }
 	    $_members{$arg} = 1;
@@ -1325,7 +1331,7 @@ sub dump_enum($$) {
 	while (my ($k, $v) = each %parameterdescs) {
 	    if (!exists($_members{$k})) {
 	        if (show_warnings("enum", $declaration_name)) {
-		     print STDERR "${file}:$.: warning: Excess enum value '$k' description in '$declaration_name'\n";
+		     emit_warning("${file}:$.", "Excess enum value '$k' description in '$declaration_name'\n");
 		}
 	    }
         }
@@ -1367,7 +1373,7 @@ sub dump_typedef($$) {
 	$return_type =~ s/^\s+//;
 
 	if ($identifier ne $declaration_name) {
-	    print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";
+	    emit_warning("${file}:$.", "expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n");
 	    return;
 	}
 
@@ -1398,7 +1404,7 @@ sub dump_typedef($$) {
 	$declaration_name = $1;
 
 	if ($identifier ne $declaration_name) {
-	    print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";
+	    emit_warning("${file}:$.", "expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n");
 	    return;
 	}
 
@@ -1554,9 +1560,7 @@ sub push_parameter($$$$$) {
 		$parameterdescs{$param} = $undescribed;
 
 	        if (show_warnings($type, $declaration_name) && $param !~ /\./) {
-			print STDERR
-			      "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
-			++$warnings;
+			emit_warning("${file}:$.", "Function parameter or member '$param' not described in '$declaration_name'\n");
 		}
 	}
 
@@ -1604,11 +1608,10 @@ sub check_sections($$$$$) {
 		}
 		if ($err) {
 			if ($decl_type eq "function") {
-				print STDERR "${file}:$.: warning: " .
+				emit_warning("${file}:$.",
 					"Excess function parameter " .
 					"'$sects[$sx]' " .
-					"description in '$decl_name'\n";
-				++$warnings;
+					"description in '$decl_name'\n");
 			}
 		}
 	}
@@ -1629,10 +1632,9 @@ sub check_return_section {
 
         if (!defined($sections{$section_return}) ||
             $sections{$section_return} eq "") {
-                print STDERR "${file}:$.: warning: " .
+                emit_warning("${file}:$.",
                         "No description found for return value of " .
-                        "'$declaration_name'\n";
-                ++$warnings;
+                        "'$declaration_name'\n");
         }
 }
 
@@ -1714,12 +1716,12 @@ sub dump_function($$) {
 
 	create_parameterlist($args, ',', $file, $declaration_name);
     } else {
-	print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
+	emit_warning("${file}:$.", "cannot understand function prototype: '$prototype'\n");
 	return;
     }
 
     if ($identifier ne $declaration_name) {
-	print STDERR "${file}:$.: warning: expecting prototype for $identifier(). Prototype was for $declaration_name() instead\n";
+	emit_warning("${file}:$.", "expecting prototype for $identifier(). Prototype was for $declaration_name() instead\n");
 	return;
     }
 
@@ -1801,8 +1803,8 @@ sub tracepoint_munge($) {
 		$tracepointargs = $1;
 	}
 	if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
-		print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
-			     "$prototype\n";
+		emit_warning("${file}:$.", "Unrecognized tracepoint format: \n".
+			     "$prototype\n");
 	} else {
 		$prototype = "static inline void trace_$tracepointname($tracepointargs)";
 		$identifier = "trace_$identifier";
@@ -2027,22 +2029,16 @@ sub process_name($$) {
 	}
 
 	if (!$is_kernel_comment) {
-	    print STDERR "${file}:$.: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n";
-	    print STDERR $_;
-	    ++$warnings;
+	    emit_warning("${file}:$.", "This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n$_");
 	    $state = STATE_NORMAL;
 	}
 
 	if (($declaration_purpose eq "") && $verbose) {
-	    print STDERR "${file}:$.: warning: missing initial short description on line:\n";
-	    print STDERR $_;
-	    ++$warnings;
+	    emit_warning("${file}:$.", "missing initial short description on line:\n$_");
 	}
 
 	if ($identifier eq "" && $decl_type ne "enum") {
-	    print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n";
-	    print STDERR $_;
-	    ++$warnings;
+	    emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n$_");
 	    $state = STATE_NORMAL;
 	}
 
@@ -2050,9 +2046,7 @@ sub process_name($$) {
 	    print STDERR "${file}:$.: info: Scanning doc for $decl_type $identifier\n";
 	}
     } else {
-	print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
-	    " - I thought it was a doc line\n";
-	++$warnings;
+	emit_warning("${file}:$.", "Cannot understand $_ on line $. - I thought it was a doc line\n");
 	$state = STATE_NORMAL;
     }
 }
@@ -2071,8 +2065,7 @@ sub process_body($$) {
 	$section =~ s/\.\.\.$//;
 
 	if ($verbose) {
-	    print STDERR "${file}:$.: warning: Variable macro arguments should be documented without dots\n";
-	    ++$warnings;
+	    emit_warning("${file}:$.", "Variable macro arguments should be documented without dots\n");
 	}
     }
 
@@ -2101,8 +2094,7 @@ sub process_body($$) {
 
 	if (($contents ne "") && ($contents ne "\n")) {
 	    if (!$in_doc_sect && $verbose) {
-		print STDERR "${file}:$.: warning: contents before sections\n";
-		++$warnings;
+		emit_warning("${file}:$.", "contents before sections\n");
 	    }
 	    dump_section($file, $section, $contents);
 	    $section = $section_default;
@@ -2128,8 +2120,7 @@ sub process_body($$) {
 	}
 	# look for doc_com + <text> + doc_end:
 	if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
-	    print STDERR "${file}:$.: warning: suspicious ending line: $_";
-	    ++$warnings;
+	    emit_warning("${file}:$.", "suspicious ending line: $_");
 	}
 
 	$prototype = "";
@@ -2173,8 +2164,7 @@ sub process_body($$) {
 	}
     } else {
 	# i dont know - bad line?  ignore.
-	print STDERR "${file}:$.: warning: bad line: $_";
-	++$warnings;
+	emit_warning("${file}:$.", "bad line: $_");
     }
 }
 
@@ -2268,9 +2258,7 @@ sub process_inline($$) {
 	    }
 	} elsif ($inline_doc_state == STATE_INLINE_NAME) {
 	    $inline_doc_state = STATE_INLINE_ERROR;
-	    print STDERR "${file}:$.: warning: ";
-	    print STDERR "Incorrect use of kernel-doc format: $_";
-	    ++$warnings;
+	    emit_warning("${file}:$.", "Incorrect use of kernel-doc format: $_");
 	}
     }
 }
@@ -2319,11 +2307,11 @@ sub process_file($) {
     if ($initial_section_counter == $section_counter && $
 	output_mode ne "none") {
 	if ($output_selection == OUTPUT_INCLUDE) {
-	    print STDERR "${file}:1: warning: '$_' not found\n"
+	    emit_warning("${file}:1", "'$_' not found\n")
 		for keys %function_table;
 	}
 	else {
-	    print STDERR "${file}:1: warning: no structured comments found\n";
+	    emit_warning("${file}:1", "no structured comments found\n");
 	}
     }
     close IN_FILE;
Signature · 1 line
2.36.1
maintainer Applied
#1 lore raw
Quoted 36 lines · Niklas Söderlund

Some warnings do not increment the warnings counter making the behavior of running kernel-doc with -Werror unlogical as some warnings will be generated but not treated as errors.

Fix this by creating a helper function that always incrementing the warnings counter every time a warning is emitted. There is one location in get_sphinx_version() where a warning is not touched as it concerns the execution environment of the kernel-doc and not the documentation being processed.

Incrementing the counter only have effect when running kernel-doc in either verbose mode (-v or environment variable KBUILD_VERBOSE) or when treating warnings as errors (-Werror or environment variable KDOC_WERROR). In both cases the number of warnings printed is printed to stderr and for the later the exit code of kernel-doc is non-zero if warnings where encountered.

Simple test case to demo one of the warnings,

    $ cat test.c
    /**
     * foo() - Description
     */
    int bar();

# Without this change
$ ./scripts/kernel-doc -Werror -none test.c
test.c:4: warning: expecting prototype for foo(). Prototype was for bar() instead

# With this change
$ ./scripts/kernel-doc -Werror -none test.c
test.c:4: warning: expecting prototype for foo(). Prototype was for bar() instead
1 warnings as Errors

Quoted 6 lines

---
* Changes since v1
- Added a helper emit_warning() to print the message and increment the counter instead of adding statements to increment the counter where it was missing.

Thanks for making this change. Anything that rationalizes this horrific script even a little bit is more than welcome.

I've applied the patch, thanks.

jon