[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH 2/6] docs: tweak kernel-doc for QEMU coding standards
From: |
Paolo Bonzini |
Subject: |
[PATCH 2/6] docs: tweak kernel-doc for QEMU coding standards |
Date: |
Tue, 29 Oct 2019 17:22:44 +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 81dc91760b..af470eb321 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';
--
2.21.0
- [RFC PATCH 0/6] docs: integrate doc comments with Sphinx build, Paolo Bonzini, 2019/10/29
- [PATCH 2/6] docs: tweak kernel-doc for QEMU coding standards,
Paolo Bonzini <=
- [PATCH 5/6] docs: add memory API reference, Paolo Bonzini, 2019/10/29
- [PATCH 4/6] memory: adjust API documentation to (modified) kerneldoc format, Paolo Bonzini, 2019/10/29
- [PATCH 3/6] docs: disable sphinx warning about missing cross references, Paolo Bonzini, 2019/10/29
- [PATCH 6/6] memory: include MemoryListener documentation and some missing function parameters, Paolo Bonzini, 2019/10/29
- [PATCH 1/6] docs: import Linux kernel-doc script and extension, Paolo Bonzini, 2019/10/29
- Re: [RFC PATCH 0/6] docs: integrate doc comments with Sphinx build, no-reply, 2019/10/29
- Re: [RFC PATCH 0/6] docs: integrate doc comments with Sphinx build, Peter Maydell, 2019/10/29