[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[PATCH 03/29] scripts/kernel-doc: Add support for named variable macro a

From: Paolo Bonzini
Subject: [PATCH 03/29] scripts/kernel-doc: Add support for named variable macro arguments
Date: Tue, 17 Nov 2020 17:52:46 +0100

From: Jonathan Neuschäfer <j.neuschaefer@gmx.net>

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 
   ./include/linux/rculist.h:651: warning:
        Excess function parameter 'cond' description in 

 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 

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>
 scripts/kernel-doc | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 2f421b7313..0f67664165 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -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 
+             $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;

reply via email to

[Prev in Thread] Current Thread [Next in Thread]