linux-kernel - [PATCH] scripts: kernel-doc: Always increment warnings counter

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-Id: <20220608142601.832926-1-niklas.soderlund@corigine.com>
Date:   Wed,  8 Jun 2022 16:26:01 +0200
From:   Niklas Söderlund <niklas.soderlund@...igine.com>
To:     Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org
Cc:     linux-kernel@...r.kernel.org, oss-drivers@...igine.com,
        Niklas Söderlund <niklas.soderlund@...igine.com>,
        Simon Horman <simon.horman@...igine.com>,
        Louis Peens <louis.peens@...igine.com>
Subject: [PATCH] scripts: kernel-doc: Always increment warnings counter

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

Fix this by always incrementing the warnings counter every time a
warning related to the input documentation is generated. There is one
location in get_sphinx_version() where a warning is printed and the
counter 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

Signed-off-by: Niklas Söderlund <niklas.soderlund@...igine.com>
Signed-off-by: Simon Horman <simon.horman@...igine.com>
Signed-off-by: Louis Peens <louis.peens@...igine.com>
---
 scripts/kernel-doc | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 7516949bb049e39f..0d1bde9e44f98d39 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1095,6 +1095,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";
+	    ++$warnings;
 	    return;
 	}
 
@@ -1302,6 +1303,7 @@ sub dump_enum($$) {
 	    } else {
 		print STDERR "${file}:$.: warning: expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n";
 	    }
+	    ++$warnings;
 	    return;
 	}
 	$declaration_name = "(anonymous)" if ($declaration_name eq "");
@@ -1317,6 +1319,7 @@ sub dump_enum($$) {
 		$parameterdescs{$arg} = $undescribed;
 	        if (show_warnings("enum", $declaration_name)) {
 			print STDERR "${file}:$.: warning: Enum value '$arg' not described in enum '$declaration_name'\n";
+			++$warnings;
 		}
 	    }
 	    $_members{$arg} = 1;
@@ -1326,6 +1329,7 @@ sub dump_enum($$) {
 	    if (!exists($_members{$k})) {
 	        if (show_warnings("enum", $declaration_name)) {
 		     print STDERR "${file}:$.: warning: Excess enum value '$k' description in '$declaration_name'\n";
+		     ++$warnings;
 		}
 	    }
         }
@@ -1368,6 +1372,7 @@ sub dump_typedef($$) {
 
 	if ($identifier ne $declaration_name) {
 	    print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";
+	    ++$warnings;
 	    return;
 	}
 
@@ -1399,6 +1404,7 @@ sub dump_typedef($$) {
 
 	if ($identifier ne $declaration_name) {
 	    print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";
+	    ++$warnings;
 	    return;
 	}
 
@@ -1715,11 +1721,13 @@ sub dump_function($$) {
 	create_parameterlist($args, ',', $file, $declaration_name);
     } else {
 	print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
+	++$warnings;
 	return;
     }
 
     if ($identifier ne $declaration_name) {
 	print STDERR "${file}:$.: warning: expecting prototype for $identifier(). Prototype was for $declaration_name() instead\n";
+	++$warnings;
 	return;
     }
 
@@ -1803,6 +1811,7 @@ sub tracepoint_munge($) {
 	if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
 		print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
 			     "$prototype\n";
+		++$warnings;
 	} else {
 		$prototype = "static inline void trace_$tracepointname($tracepointargs)";
 		$identifier = "trace_$identifier";
@@ -2325,6 +2334,7 @@ sub process_file($) {
 	else {
 	    print STDERR "${file}:1: warning: no structured comments found\n";
 	}
+	++$warnings;
     }
     close IN_FILE;
 }
-- 
2.36.0