[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 65/87] docs: tweak kernel-doc for QEMU coding standards
From: |
Paolo Bonzini |
Subject: |
[PULL 65/87] docs: tweak kernel-doc for QEMU coding standards |
Date: |
Wed, 18 Dec 2019 13:02:31 +0100 |
Surprisingly, QEMU does have a pretty consistent doc comment style and
it is not very different from the Linux kernel's. Of the documentation
"sigils", only "#" separates the QEMU doc comment style from Linux's,
and it has 200+ instances vs. 6 for the kernel's '&struct foo' (all in
accel/tcg/translate-all.c), so it's clear that the two standards are
different in this respect. In addition, our structs are typedefed and
recognized by CamelCase names.
Adjust kernel-doc's parser for these two aspects of the QEMU coding
standards. The patch has been valid, with hardly any change, for over
two years, so it should not be an issue to keep kernel-doc in sync with
the Linux copy.
Signed-off-by: Paolo Bonzini <address@hidden>
---
scripts/kernel-doc | 28 +++++++++++++++++++---------
1 file changed, 19 insertions(+), 9 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 81dc917..af470eb 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -215,12 +215,12 @@ my $type_func = '(\w+)\(\)';
my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params
my $type_env = '(\$\w+)';
-my $type_enum = '\&(enum\s*([_\w]+))';
-my $type_struct = '\&(struct\s*([_\w]+))';
-my $type_typedef = '\&(typedef\s*([_\w]+))';
-my $type_union = '\&(union\s*([_\w]+))';
-my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
-my $type_fallback = '\&([_\w]+)';
+my $type_enum = '#(enum\s*([_\w]+))';
+my $type_struct = '#(struct\s*([_\w]+))';
+my $type_typedef = '#(([A-Z][_\w]*))';
+my $type_union = '#(union\s*([_\w]+))';
+my $type_member = '#([_\w]+)(\.|->)([_\w]+)';
+my $type_fallback = '(?!)'; # this never matches
my $type_member_func = $type_member . '\(\)';
# Output conversion substitutions.
@@ -1050,6 +1050,14 @@ sub output_blockhead {
sub dump_declaration($$) {
no strict 'refs';
my ($prototype, $file) = @_;
+ if ($decl_type eq 'type name') {
+ if ($prototype =~ /^(enum|struct|union)\s+/) {
+ $decl_type = $1;
+ } else {
+ return;
+ }
+ }
+
my $func = "dump_" . $decl_type;
&$func(@_);
}
@@ -1878,7 +1886,7 @@ sub process_name($$) {
}
elsif (/$doc_decl/o) {
$identifier = $1;
- if (/\s*([\w\s]+?)(\(\))?\s*-/) {
+ if (/\s*([\w\s]+?)(\s*-|:)/) {
$identifier = $1;
}
@@ -1888,7 +1896,7 @@ sub process_name($$) {
$contents = "";
$section = $section_default;
$new_start_line = $. + 1;
- if (/-(.*)/) {
+ if (/[-:](.*)/) {
# strip leading/trailing/multiple spaces
$descr= $1;
$descr =~ s/^\s*//;
@@ -1906,7 +1914,9 @@ sub process_name($$) {
++$warnings;
}
- if ($identifier =~ m/^struct\b/) {
+ if ($identifier =~ m/^[A-Z]/) {
+ $decl_type = 'type name';
+ } elsif ($identifier =~ m/^struct\b/) {
$decl_type = 'struct';
} elsif ($identifier =~ m/^union\b/) {
$decl_type = 'union';
--
1.8.3.1
- [PULL 55/87] hw/isa/isa-bus: cleanup irq functions, (continued)
- [PULL 55/87] hw/isa/isa-bus: cleanup irq functions, Paolo Bonzini, 2019/12/18
- [PULL 54/87] hw/i386: Simplify ioapic_init_gsi(), Paolo Bonzini, 2019/12/18
- [PULL 57/87] hw/i386/pc: Inline port92_init(), Paolo Bonzini, 2019/12/18
- [PULL 56/87] hw/i386/pc: Use TYPE_PORT92 instead of hardcoded string, Paolo Bonzini, 2019/12/18
- [PULL 58/87] hw/i386/pc: Extract the port92 device, Paolo Bonzini, 2019/12/18
- [PULL 59/87] hyperv: Use auto rcu_read macros, Paolo Bonzini, 2019/12/18
- [PULL 60/87] qsp: Use WITH_RCU_READ_LOCK_GUARD, Paolo Bonzini, 2019/12/18
- [PULL 61/87] memory: use RCU_READ_LOCK_GUARD, Paolo Bonzini, 2019/12/18
- [PULL 62/87] colo: fix return without releasing RCU, Paolo Bonzini, 2019/12/18
- [PULL 63/87] build: rename CONFIG_LIBCAP to CONFIG_LIBCAP_NG, Paolo Bonzini, 2019/12/18
- [PULL 65/87] docs: tweak kernel-doc for QEMU coding standards,
Paolo Bonzini <=
- [PULL 66/87] docs/conf.py: Enable use of kerneldoc sphinx extension, Paolo Bonzini, 2019/12/18
- [PULL 67/87] Makefile: disable Sphinx nitpicking, Paolo Bonzini, 2019/12/18
- [PULL 71/87] docs: add memory API reference, Paolo Bonzini, 2019/12/18
- [PULL 69/87] docs: Create bitops.rst as example of kernel-docs, Paolo Bonzini, 2019/12/18
- [PULL 68/87] bitops.h: Silence kernel-doc complaints, Paolo Bonzini, 2019/12/18
- [PULL 70/87] memory.h: Silence kernel-doc complaints, Paolo Bonzini, 2019/12/18
- [PULL 73/87] migration: check length directly to make sure the range is aligned, Paolo Bonzini, 2019/12/18
- [PULL 72/87] memory: include MemoryListener documentation and some missing function parameters, Paolo Bonzini, 2019/12/18
- [PULL 74/87] WHPX: refactor load library, Paolo Bonzini, 2019/12/18
- [PULL 75/87] target/i386: remove unused pci-assign codes, Paolo Bonzini, 2019/12/18