linux-kernel - [PATCH] kernel-doc: suppress 'not described' warnings for embedded struct fields

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>] [day] [month] [year] [list]

Message-ID: <20190111123841.6f195c2c@lwn.net>
Date:   Fri, 11 Jan 2019 12:39:14 -0700
From:   Jonathan Corbet <corbet@....net>
To:     linux-doc@...r.kernel.org
Cc:     Mauro Carvalho Chehab <mchehab@...radead.org>,
        LKML <linux-kernel@...r.kernel.org>
Subject: [PATCH] kernel-doc: suppress 'not described' warnings for embedded
 struct fields

The ability to add kerneldoc comments for fields in embedded structures is
useful, but it brought along a whole bunch of warnings for fields that
could not be described before.  In many cases, there's little value in
adding docs for these nested fields, and in cases like:

       	struct a {
            struct b {
	        int c;
	    } d, e;
	};

"c" would have to be described twice (as d.c and e.c) to make the warnings
go away.

We can no doubt do something smarter, but simply suppressing the warnings
for this case removes about 70 relatively useless warnings from the docs
build, freeing us to focus on the ones that matter more.  So make
kerneldoc be silent about missing descriptions for any field containing a
".".

Signed-off-by: Jonathan Corbet <corbet@....net>
---
 scripts/kernel-doc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index c5333d251985..3350e498b4ce 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1474,7 +1474,7 @@ sub push_parameter($$$$) {
 	if (!defined $parameterdescs{$param} && $param !~ /^#/) {
 		$parameterdescs{$param} = $undescribed;

-	        if (show_warnings($type, $declaration_name)) {
+	        if (show_warnings($type, $declaration_name) && $param !~ /\./) {
 			print STDERR
 			      "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
 			++$warnings;
-- 
2.20.1