From patchwork Fri Oct 23 07:34:10 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 286115 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-13.1 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 2A54AC388F9 for ; Fri, 23 Oct 2020 07:34:20 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id D1AE02192A for ; Fri, 23 Oct 2020 07:34:19 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1603438459; bh=HGvl3PsFstTdLuyU989jcm167i+3/reVhKz8iD6S2RM=; h=From:To:Cc:Subject:Date:List-ID:From; b=0IhDSvN+T4imIrlArdieePpcZLN7bJvS2/TesntJXNHbAgiY3x3Jba2tzK6NcSXD7 OPCO3i9VXm4L5KczIVNmpAI0vO1WOFlU0tyG397hwT96naiJsZ8+YLYIw41T8OoeUV ZqpreOvd7sy9R6ebf5kcXC7YLo3qByW9/yxStpdM= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S375718AbgJWHeR (ORCPT ); Fri, 23 Oct 2020 03:34:17 -0400 Received: from mail.kernel.org ([198.145.29.99]:39536 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S375714AbgJWHeQ (ORCPT ); Fri, 23 Oct 2020 03:34:16 -0400 Received: from mail.kernel.org (ip5f5ad5a3.dynamic.kabel-deutschland.de [95.90.213.163]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 6607420936; Fri, 23 Oct 2020 07:34:15 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1603438455; bh=HGvl3PsFstTdLuyU989jcm167i+3/reVhKz8iD6S2RM=; h=From:To:Cc:Subject:Date:From; b=U7FXUZiUnBV2+5F6f7hysjAtV/+02VrTbwXqV7mgvUbx6Bxw+sJ5PMh6g+128djCn ppcf80kBg7kPUg7Jtr1rm2JxZ+BgZy2Rxglc8LCTAQ82Jz4/kVUCREpRqANwjhrpKl Y6wYU7LplgfezUddhOaoIWCDj9tLEW9YwWxPCGJ8= Received: from mchehab by mail.kernel.org with local (Exim 4.94) (envelope-from ) id 1kVraW-001q9a-NR; Fri, 23 Oct 2020 09:34:12 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Media Mailing List Cc: linuxarm@huawei.com, mauro.chehab@huawei.com, Mauro Carvalho Chehab , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH] kernel-doc: validate function prototype names Date: Fri, 23 Oct 2020 09:34:10 +0200 Message-Id: X-Mailer: git-send-email 2.26.2 MIME-Version: 1.0 Sender: Mauro Carvalho Chehab Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org 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 **Parameters** ``int i`` the value to add to the refcount ``refcount_t *r`` the refcount ``int *oldp`` *undescribed* 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 Reported-by: kernel test robot Reported-by: kernel test robot --- 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) {