tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

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>

authored by

Jonathan Neuschäfer and committed by
Jonathan Corbet 43756e34 1c16b3d5

+16
+16
scripts/kernel-doc
··· 1450 1450 # handles unnamed variable parameters 1451 1451 $param = "..."; 1452 1452 } 1453 + elsif ($param =~ /\w\.\.\.$/) { 1454 + # for named variable parameters of the form `x...`, remove the dots 1455 + $param =~ s/\.\.\.$//; 1456 + } 1453 1457 if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") { 1454 1458 $parameterdescs{$param} = "variable arguments"; 1455 1459 } ··· 1940 1936 # 1941 1937 sub process_body($$) { 1942 1938 my $file = shift; 1939 + 1940 + # Until all named variable macro parameters are 1941 + # documented using the bare name (`x`) rather than with 1942 + # dots (`x...`), strip the dots: 1943 + if ($section =~ /\w\.\.\.$/) { 1944 + $section =~ s/\.\.\.$//; 1945 + 1946 + if ($verbose) { 1947 + print STDERR "${file}:$.: warning: Variable macro arguments should be documented without dots\n"; 1948 + ++$warnings; 1949 + } 1950 + } 1943 1951 1944 1952 if (/$doc_sect/i) { # case insensitive for supported section names 1945 1953 $newsection = $1;