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@xxxxxxx> > Cc: Paul E. McKenney <paulmck@xxxxxxxxxx> Tested-by: Paul E. McKenney <paulmck@xxxxxxxxxx> > --- > 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 >
