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

Niklas Söderlund committed 4 years ago

Commit df4bf981 parent b13bacc1 file · +35 −47Browse files

Unified · Split

scripts/kernel-doc+35−47

         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.
 #
 	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";
+		emit_warning("${file}:$.", "duplicate section name '$name'\n");
-		++$warnings;
 	    }
 	    $sections{$name} .= $contents;
 	} else {
     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;
 	}
     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;
 	}
 	    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;
 	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");
 		}
 	    }
         }
 	$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;
 	}
 	$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;
 	}
 		$parameterdescs{$param} = $undescribed;
 	        if (show_warnings($type, $declaration_name) && $param !~ /\./) {
-			print STDERR
+			emit_warning("${file}:$.", "Function parameter or member '$param' not described in '$declaration_name'\n");
-			      "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
-			++$warnings;
 		}
 	}
 		}
 		if ($err) {
 			if ($decl_type eq "function") {
-				print STDERR "${file}:$.: warning: " .
+				emit_warning("${file}:$.",
 					"Excess function parameter " .
 					"'$sects[$sx]' " .
-					"description in '$decl_name'\n";
+					"description in '$decl_name'\n");
-				++$warnings;
 			}
 		}
 	}
         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";
+                        "'$declaration_name'\n");
-                ++$warnings;
         }
 }
 	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;
     }
 		$tracepointargs = $1;
 	}
 	if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
-		print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
+		emit_warning("${file}:$.", "Unrecognized tracepoint format: \n".
-			     "$prototype\n";
+			     "$prototype\n");
 	} else {
 		$prototype = "static inline void trace_$tracepointname($tracepointargs)";
 		$identifier = "trace_$identifier";
 	}
 	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";
+	    emit_warning("${file}:$.", "This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n$_");
-	    print STDERR $_;
-	    ++$warnings;
 	    $state = STATE_NORMAL;
 	}
 	if (($declaration_purpose eq "") && $verbose) {
-	    print STDERR "${file}:$.: warning: missing initial short description on line:\n";
+	    emit_warning("${file}:$.", "missing initial short description on line:\n$_");
-	    print STDERR $_;
-	    ++$warnings;
 	}
 	if ($identifier eq "" && $decl_type ne "enum") {
-	    print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n";
+	    emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n$_");
-	    print STDERR $_;
-	    ++$warnings;
 	    $state = STATE_NORMAL;
 	}
 	    print STDERR "${file}:$.: info: Scanning doc for $decl_type $identifier\n";
 	}
     } else {
-	print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
+	emit_warning("${file}:$.", "Cannot understand $_ on line $. - I thought it was a doc line\n");
-	    " - I thought it was a doc line\n";
-	++$warnings;
 	$state = STATE_NORMAL;
     }
 }
 	$section =~ s/\.\.\.$//;
 	if ($verbose) {
-	    print STDERR "${file}:$.: warning: Variable macro arguments should be documented without dots\n";
+	    emit_warning("${file}:$.", "Variable macro arguments should be documented without dots\n");
-	    ++$warnings;
 	}
     }
 	if (($contents ne "") && ($contents ne "\n")) {
 	    if (!$in_doc_sect && $verbose) {
-		print STDERR "${file}:$.: warning: contents before sections\n";
+		emit_warning("${file}:$.", "contents before sections\n");
-		++$warnings;
 	    }
 	    dump_section($file, $section, $contents);
 	    $section = $section_default;
 	}
 	# look for doc_com + <text> + doc_end:
 	if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
-	    print STDERR "${file}:$.: warning: suspicious ending line: $_";
+	    emit_warning("${file}:$.", "suspicious ending line: $_");
-	    ++$warnings;
 	}
 	$prototype = "";
 	}
     } else {
 	# i dont know - bad line?  ignore.
-	print STDERR "${file}:$.: warning: bad line: $_";
+	emit_warning("${file}:$.", "bad line: $_");
-	++$warnings;
     }
 }
 	    }
 	} elsif ($inline_doc_state == STATE_INLINE_NAME) {
 	    $inline_doc_state = STATE_INLINE_ERROR;
-	    print STDERR "${file}:$.: warning: ";
+	    emit_warning("${file}:$.", "Incorrect use of kernel-doc format: $_");
-	    print STDERR "Incorrect use of kernel-doc format: $_";
-	    ++$warnings;
 	}
     }
 }
     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;