mirror of
https://gitlab.com/qemu-project/qemu
synced 2024-09-06 01:43:39 +00:00
scripts/kernel-doc: Add support for named variable macro arguments
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> Tested-by: Paul E. McKenney <paulmck@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Message-Id: <20201117165312.118257-4-pbonzini@redhat.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
This commit is contained in:
parent
b5a8dfb532
commit
65fb67bf73
|
@ -1480,6 +1480,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";
|
||||
}
|
||||
|
@ -1967,6 +1971,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;
|
||||
|
|
Loading…
Reference in a new issue