Linux-Media Archive on
 help / color / Atom feed
From: Mauro Carvalho Chehab <>
To: Jonathan Corbet <>,
	Linux Media Mailing List <>
	Mauro Carvalho Chehab <>,,
Subject: [PATCH] kernel-doc: validate function prototype names
Date: Fri, 23 Oct 2020 09:34:10 +0200
Message-ID: <> (raw)

Kernel-doc currently expects that the kernel-doc markup to come
just before the function prototype. Yet, if it find things like:

	 * refcount_add - add a value to a refcount
	 * @i: the value to add to the refcount
	 * @r: the refcount
	static inline void __refcount_add(int i, refcount_t *r, int *oldp);
	static inline void refcount_add(int i, refcount_t *r);

Kernel-doc will do the wrong thing:

	foobar.h:6: warning: Function parameter or member 'oldp' not described in '__refcount_add'
	.. c:function:: void __refcount_add (int i, refcount_t *r, int *oldp)

	   add a value to a refcount


	``int i``
	  the value to add to the refcount

	``refcount_t *r``
	  the refcount

	``int *oldp``

Basically, it will document "__refcount_add" with the kernel-doc
markup for refcount_add.

If both functions have the same arguments, this won't even
produce any warning!

Add a logic to check function identifiers, warning about
wrong identifiers and not documenting them.

Signed-off-by: Mauro Carvalho Chehab <>
 scripts/kernel-doc | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 99cd8418ff8a..c879e69262dd 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -382,6 +382,9 @@ my $inline_doc_state;
 # 'function', 'struct', 'union', 'enum', 'typedef'
 my $decl_type;
+# On functions, this should match the name of the function
+my $identifier;
 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
 my $doc_end = '\*/';
 my $doc_com = '\s*\*\s*';
@@ -1785,6 +1788,11 @@ sub dump_function($$) {
 	$declaration_name = $2;
 	my $args = $3;
+	if ($identifier ne $declaration_name) {
+	    print STDERR "${file}:$.: warning: expecting prototype for function $identifier. Prototype was for function $declaration_name instead\n";
+	    return;
+	}
 	create_parameterlist($args, ',', $file, $declaration_name);
     } else {
 	print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
@@ -2036,7 +2044,6 @@ sub process_normal() {
 sub process_name($$) {
     my $file = shift;
-    my $identifier;
     my $descr;
     if (/$doc_block/o) {

             reply index

Thread overview: 3+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-10-23  7:34 Mauro Carvalho Chehab [this message]
2020-10-23 10:18 ` kernel test robot
2020-10-23 10:18 ` kernel test robot

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \ \ \ \ \ \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Linux-Media Archive on

Archives are clonable:
	git clone --mirror linux-media/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-media linux-media/ \
	public-inbox-index linux-media

Example config snippet for mirrors

Newsgroup available over NNTP:

AGPL code for this site: git clone