[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 085/113] scripts/kernel-doc: Add support for named variable macro
From: |
Paolo Bonzini |
Subject: |
[PULL 085/113] scripts/kernel-doc: Add support for named variable macro arguments |
Date: |
Wed, 2 Dec 2020 03:08:21 -0500 |
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
'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>
---
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
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;
--
2.26.2
- [PULL 073/113] migration, vl: start migration via qmp_migrate_incoming, (continued)
- [PULL 073/113] migration, vl: start migration via qmp_migrate_incoming, Paolo Bonzini, 2020/12/02
- [PULL 068/113] vl: separate qemu_create_machine, Paolo Bonzini, 2020/12/02
- [PULL 079/113] vl: remove serial_max_hds, Paolo Bonzini, 2020/12/02
- [PULL 075/113] hmp: introduce cmd_available, Paolo Bonzini, 2020/12/02
- [PULL 077/113] vl: extract machine done notifiers, Paolo Bonzini, 2020/12/02
- [PULL 094/113] kernel-doc: add support for ____cacheline_aligned attribute, Paolo Bonzini, 2020/12/02
- [PULL 096/113] Revert "scripts/kerneldoc: For Sphinx 3 use c:macro for macros with arguments", Paolo Bonzini, 2020/12/02
- [PULL 083/113] kernel-doc: fix processing nested structs with attributes, Paolo Bonzini, 2020/12/02
- [PULL 082/113] docs: temporarily disable the kernel-doc extension, Paolo Bonzini, 2020/12/02
- [PULL 081/113] config-file: move -set implementation to vl.c, Paolo Bonzini, 2020/12/02
- [PULL 085/113] scripts/kernel-doc: Add support for named variable macro arguments,
Paolo Bonzini <=
- [PULL 089/113] Replace HTTP links with HTTPS ones: documentation, Paolo Bonzini, 2020/12/02
- [PULL 092/113] scripts/kernel-doc: optionally treat warnings as errors, Paolo Bonzini, 2020/12/02
- [PULL 095/113] scripts: kernel-doc: add support for typedef enum, Paolo Bonzini, 2020/12/02
- [PULL 097/113] Revert "kernel-doc: Use c:struct for Sphinx 3.0 and later", Paolo Bonzini, 2020/12/02
- [PULL 102/113] scripts: kernel-doc: fix typedef identification, Paolo Bonzini, 2020/12/02
- [PULL 098/113] scripts: kernel-doc: make it more compatible with Sphinx 3.x, Paolo Bonzini, 2020/12/02
- [PULL 107/113] Revert "kernel-doc: Handle function typedefs without asterisks", Paolo Bonzini, 2020/12/02
- [PULL 104/113] scripts: kernel-doc: allow passing desired Sphinx C domain dialect, Paolo Bonzini, 2020/12/02
- [PULL 078/113] vl: extract softmmu/rtc.c, Paolo Bonzini, 2020/12/02
- [PULL 093/113] kernel-doc: include line numbers for function prototypes, Paolo Bonzini, 2020/12/02