diff options
author | Jonathan Neuschäfer <j.neuschaefer@gmx.net> | 2019-11-07 14:41:33 +0100 |
---|---|---|
committer | Jonathan Corbet <corbet@lwn.net> | 2019-11-07 13:17:24 -0700 |
commit | 43756e347f213b68f884c3b4082e95e7f98204f1 (patch) | |
tree | 1649883e9c527ec10cf9710947cd598168344c2e /scripts | |
parent | 1c16b3d58681b583157a1b74c4c4dd96a08f5931 (diff) | |
download | linux-43756e347f213b68f884c3b4082e95e7f98204f1.tar.gz linux-43756e347f213b68f884c3b4082e95e7f98204f1.tar.bz2 linux-43756e347f213b68f884c3b4082e95e7f98204f1.zip |
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>
Diffstat (limited to 'scripts')
-rwxr-xr-x | scripts/kernel-doc | 16 |
1 files changed, 16 insertions, 0 deletions
diff --git a/scripts/kernel-doc b/scripts/kernel-doc index a529375c8536..f2d73f04e71d 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1450,6 +1450,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"; } @@ -1937,6 +1941,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; |