History

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
@@ -427,6 +427,13 @@ sub print_lineno { · 426 unmodified lines
427427 print ".. LINENO " . $lineno . "\n";
428428 }
429429 }
430+
431+sub emit_warning {
432+ my $location = shift;
433+ my $msg = shift;
434+ print STDERR "$location: warning: $msg";
435+ ++$warnings;
436+}
430437 ##
431438 # dumps section contents to arrays/hashes intended for that purpose.
432439 #
@@ -451,8 +458,7 @@ sub dump_section { · 18 unmodified lines
451458 if (defined($sections{$name}) && ($sections{$name} ne "")) {
452459 # Only warn on user specified duplicate section names.
453460 if ($name ne $section_default) {
454− print STDERR "${file}:$.: warning: duplicate section name '$name'\n";
455− ++$warnings;
461+ emit_warning("${file}:$.", "duplicate section name '$name'\n");
456462 }
457463 $sections{$name} .= $contents;
458464 } else {
@@ -1094,7 +1100,7 @@ sub dump_struct($$) { · 635 unmodified lines
10941100
10951101 if ($members) {
10961102 if ($identifier ne $declaration_name) {
1097− print STDERR "${file}:$.: warning: expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n";
1103+ emit_warning("${file}:$.", "expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n");
10981104 return;
10991105 }
11001106
@@ -1298,9 +1304,9 @@ sub dump_enum($$) { · 197 unmodified lines
12981304 if ($members) {
12991305 if ($identifier ne $declaration_name) {
13001306 if ($identifier eq "") {
1301− print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n";
1307+ emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n");
13021308 } else {
1303− print STDERR "${file}:$.: warning: expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n";
1309+ emit_warning("${file}:$.", "expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n");
13041310 }
13051311 return;
13061312 }
@@ -1316,7 +1322,7 @@ sub dump_enum($$) { · 9 unmodified lines
13161322 if (!$parameterdescs{$arg}) {
13171323 $parameterdescs{$arg} = $undescribed;
13181324 if (show_warnings("enum", $declaration_name)) {
1319− print STDERR "${file}:$.: warning: Enum value '$arg' not described in enum '$declaration_name'\n";
1325+ emit_warning("${file}:$.", "Enum value '$arg' not described in enum '$declaration_name'\n");
13201326 }
13211327 }
13221328 $_members{$arg} = 1;
@@ -1325,7 +1331,7 @@ sub dump_enum($$) { · 2 unmodified lines
13251331 while (my ($k, $v) = each %parameterdescs) {
13261332 if (!exists($_members{$k})) {
13271333 if (show_warnings("enum", $declaration_name)) {
1328− print STDERR "${file}:$.: warning: Excess enum value '$k' description in '$declaration_name'\n";
1334+ emit_warning("${file}:$.", "Excess enum value '$k' description in '$declaration_name'\n");
13291335 }
13301336 }
13311337 }
@@ -1367,7 +1373,7 @@ sub dump_typedef($$) { · 35 unmodified lines
13671373 $return_type =~ s/^\s+//;
13681374
13691375 if ($identifier ne $declaration_name) {
1370− print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";
1376+ emit_warning("${file}:$.", "expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n");
13711377 return;
13721378 }
13731379
@@ -1398,7 +1404,7 @@ sub dump_typedef($$) { · 24 unmodified lines
13981404 $declaration_name = $1;
13991405
14001406 if ($identifier ne $declaration_name) {
1401− print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";
1407+ emit_warning("${file}:$.", "expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n");
14021408 return;
14031409 }
14041410
@@ -1554,9 +1560,7 @@ sub push_parameter($$$$$) { · 149 unmodified lines
15541560 $parameterdescs{$param} = $undescribed;
15551561
15561562 if (show_warnings($type, $declaration_name) && $param !~ /\./) {
1557− print STDERR
1558− "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
1559− ++$warnings;
1563+ emit_warning("${file}:$.", "Function parameter or member '$param' not described in '$declaration_name'\n");
15601564 }
15611565 }
15621566
@@ -1604,11 +1608,10 @@ sub check_sections($$$$$) { · 41 unmodified lines
16041608 }
16051609 if ($err) {
16061610 if ($decl_type eq "function") {
1607− print STDERR "${file}:$.: warning: " .
1611+ emit_warning("${file}:$.",
16081612 "Excess function parameter " .
16091613 "'$sects[$sx]' " .
1610− "description in '$decl_name'\n";
1611− ++$warnings;
1614+ "description in '$decl_name'\n");
16121615 }
16131616 }
16141617 }
@@ -1629,10 +1632,9 @@ sub check_return_section { · 14 unmodified lines
16291632
16301633 if (!defined($sections{$section_return}) ||
16311634 $sections{$section_return} eq "") {
1632− print STDERR "${file}:$.: warning: " .
1635+ emit_warning("${file}:$.",
16331636 "No description found for return value of " .
1634− "'$declaration_name'\n";
1635− ++$warnings;
1637+ "'$declaration_name'\n");
16361638 }
16371639 }
16381640
@@ -1714,12 +1716,12 @@ sub dump_function($$) { · 75 unmodified lines
17141716
17151717 create_parameterlist($args, ',', $file, $declaration_name);
17161718 } else {
1717− print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
1719+ emit_warning("${file}:$.", "cannot understand function prototype: '$prototype'\n");
17181720 return;
17191721 }
17201722
17211723 if ($identifier ne $declaration_name) {
1722− print STDERR "${file}:$.: warning: expecting prototype for $identifier(). Prototype was for $declaration_name() instead\n";
1724+ emit_warning("${file}:$.", "expecting prototype for $identifier(). Prototype was for $declaration_name() instead\n");
17231725 return;
17241726 }
17251727
@@ -1801,8 +1803,8 @@ sub tracepoint_munge($) { · 75 unmodified lines
18011803 $tracepointargs = $1;
18021804 }
18031805 if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
1804− print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
1805− "$prototype\n";
1806+ emit_warning("${file}:$.", "Unrecognized tracepoint format: \n".
1807+ "$prototype\n");
18061808 } else {
18071809 $prototype = "static inline void trace_$tracepointname($tracepointargs)";
18081810 $identifier = "trace_$identifier";
@@ -2027,22 +2029,16 @@ sub process_name($$) { · 218 unmodified lines
20272029 }
20282030
20292031 if (!$is_kernel_comment) {
2030− print STDERR "${file}:$.: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n";
2031− print STDERR $_;
2032− ++$warnings;
2032+ emit_warning("${file}:$.", "This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n$_");
20332033 $state = STATE_NORMAL;
20342034 }
20352035
20362036 if (($declaration_purpose eq "") && $verbose) {
2037− print STDERR "${file}:$.: warning: missing initial short description on line:\n";
2038− print STDERR $_;
2039− ++$warnings;
2037+ emit_warning("${file}:$.", "missing initial short description on line:\n$_");
20402038 }
20412039
20422040 if ($identifier eq "" && $decl_type ne "enum") {
2043− print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n";
2044− print STDERR $_;
2045− ++$warnings;
2041+ emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n$_");
20462042 $state = STATE_NORMAL;
20472043 }
20482044
@@ -2050,9 +2046,7 @@ sub process_name($$) { · 1 unmodified line
20502046 print STDERR "${file}:$.: info: Scanning doc for $decl_type $identifier\n";
20512047 }
20522048 } else {
2053− print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
2054− " - I thought it was a doc line\n";
2055− ++$warnings;
2049+ emit_warning("${file}:$.", "Cannot understand $_ on line $. - I thought it was a doc line\n");
20562050 $state = STATE_NORMAL;
20572051 }
20582052 }
@@ -2071,8 +2065,7 @@ sub process_body($$) { · 12 unmodified lines
20712065 $section =~ s/\.\.\.$//;
20722066
20732067 if ($verbose) {
2074− print STDERR "${file}:$.: warning: Variable macro arguments should be documented without dots\n";
2075− ++$warnings;
2068+ emit_warning("${file}:$.", "Variable macro arguments should be documented without dots\n");
20762069 }
20772070 }
20782071
@@ -2101,8 +2094,7 @@ sub process_body($$) { · 22 unmodified lines
21012094
21022095 if (($contents ne "") && ($contents ne "\n")) {
21032096 if (!$in_doc_sect && $verbose) {
2104− print STDERR "${file}:$.: warning: contents before sections\n";
2105− ++$warnings;
2097+ emit_warning("${file}:$.", "contents before sections\n");
21062098 }
21072099 dump_section($file, $section, $contents);
21082100 $section = $section_default;
@@ -2128,8 +2120,7 @@ sub process_body($$) { · 19 unmodified lines
21282120 }
21292121 # look for doc_com + <text> + doc_end:
21302122 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2131− print STDERR "${file}:$.: warning: suspicious ending line: $_";
2132− ++$warnings;
2123+ emit_warning("${file}:$.", "suspicious ending line: $_");
21332124 }
21342125
21352126 $prototype = "";
@@ -2173,8 +2164,7 @@ sub process_body($$) { · 37 unmodified lines
21732164 }
21742165 } else {
21752166 # i dont know - bad line? ignore.
2176− print STDERR "${file}:$.: warning: bad line: $_";
2177− ++$warnings;
2167+ emit_warning("${file}:$.", "bad line: $_");
21782168 }
21792169 }
21802170
@@ -2268,9 +2258,7 @@ sub process_inline($$) { · 87 unmodified lines
22682258 }
22692259 } elsif ($inline_doc_state == STATE_INLINE_NAME) {
22702260 $inline_doc_state = STATE_INLINE_ERROR;
2271− print STDERR "${file}:$.: warning: ";
2272− print STDERR "Incorrect use of kernel-doc format: $_";
2273− ++$warnings;
2261+ emit_warning("${file}:$.", "Incorrect use of kernel-doc format: $_");
22742262 }
22752263 }
22762264 }
@@ -2319,11 +2307,11 @@ sub process_file($) { · 42 unmodified lines
23192307 if ($initial_section_counter == $section_counter && $
23202308 output_mode ne "none") {
23212309 if ($output_selection == OUTPUT_INCLUDE) {
2322− print STDERR "${file}:1: warning: '$_' not found\n"
2310+ emit_warning("${file}:1", "'$_' not found\n")
23232311 for keys %function_table;
23242312 }
23252313 else {
2326− print STDERR "${file}:1: warning: no structured comments found\n";
2314+ emit_warning("${file}:1", "no structured comments found\n");
23272315 }
23282316 }
23292317 close IN_FILE;