Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Date:   Thu, 7 Nov 2019 06:27:48 -0800
From:   "Paul E. McKenney" <paulmck@kernel.org>
To:     Jonathan =?iso-8859-1?Q?Neusch=E4fer?= <j.neuschaefer@gmx.net>
Cc:     linux-doc@vger.kernel.org, Joel Fernandes <joel@joelfernandes.org>,
        Jonathan Corbet <corbet@lwn.net>, linux-kernel@vger.kernel.org
Subject: Re: [PATCH] scripts/kernel-doc: Add support for named variable macro
 arguments
Message-ID: <20191107142748.GN20975@paulmck-ThinkPad-P72>
Reply-To: paulmck@kernel.org
References: <20191107134133.14690-1-j.neuschaefer@gmx.net>
MIME-Version: 1.0
Content-Type: text/plain; charset=iso-8859-1
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <20191107134133.14690-1-j.neuschaefer@gmx.net>
User-Agent: Mutt/1.9.4 (2018-02-28)
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

On Thu, Nov 07, 2019 at 02:41:33PM +0100, Jonathan Neusch?fer wrote:
> Currently, when kernel-doc encounters a macro with a named variable
> argument[1], such as this:
> 
>    #define hlist_for_each_entry_rcu(pos, head, member, cond...)
> 
> ... it expects the variable argument to be documented as `cond...`,
> rather than `cond`. This is semantically wrong, because the name (as
> used in the macro body) is actually `cond`.
> 
> With this patch, kernel-doc will accept the name without dots (`cond`
> in the example above) in doc comments, and warn if the name with dots
> (`cond...`) is used and verbose mode[2] is enabled.
> 
> The support for the `cond...` syntax can be removed later, when the
> documentation of all such macros has been switched to the new syntax.
> 
> Testing this patch on top of v5.4-rc6, `make htmldocs` shows a few
> changes in log output and HTML output:
> 
>  1) The following warnings[3] are eliminated:
> 
>    ./include/linux/rculist.h:374: warning:
>         Excess function parameter 'cond' description in 'list_for_each_entry_rcu'
>    ./include/linux/rculist.h:651: warning:
>         Excess function parameter 'cond' description in 'hlist_for_each_entry_rcu'
> 
>  2) For list_for_each_entry_rcu and hlist_for_each_entry_rcu, the
>     correct description is shown
> 
>  3) Named variable arguments are shown without dots
> 
> 
> [1]: https://gcc.gnu.org/onlinedocs/cpp/Variadic-Macros.html
> [2]: scripts/kernel-doc -v
> [3]: See also https://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git/commit/?h=dev&id=5bc4bc0d6153617eabde275285b7b5a8137fdf3c
> 
> Signed-off-by: Jonathan Neusch?fer <j.neuschaefer@gmx.net>
> Cc: Paul E. McKenney <paulmck@kernel.org>

Tested-by: Paul E. McKenney <paulmck@kernel.org>

> ---
>  scripts/kernel-doc | 16 ++++++++++++++++
>  1 file changed, 16 insertions(+)
> 
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 81dc91760b23..48696391eccb 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -1449,6 +1449,10 @@ sub push_parameter($$$$) {
>  	      # handles unnamed variable parameters
>  	      $param = "...";
>  	    }
> +	    elsif ($param =~ /\w\.\.\.$/) {
> +	      # for named variable parameters of the form `x...`, remove the dots
> +	      $param =~ s/\.\.\.$//;
> +	    }
>  	    if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
>  		$parameterdescs{$param} = "variable arguments";
>  	    }
> @@ -1936,6 +1940,18 @@ sub process_name($$) {
>  sub process_body($$) {
>      my $file = shift;
> 
> +    # Until all named variable macro parameters are
> +    # documented using the bare name (`x`) rather than with
> +    # dots (`x...`), strip the dots:
> +    if ($section =~ /\w\.\.\.$/) {
> +	$section =~ s/\.\.\.$//;
> +
> +	if ($verbose) {
> +	    print STDERR "${file}:$.: warning: Variable macro arguments should be documented without dots\n";
> +	    ++$warnings;
> +	}
> +    }
> +
>      if (/$doc_sect/i) { # case insensitive for supported section names
>  	$newsection = $1;
>  	$newcontents = $2;
> --
> 2.20.1
>