system/qemu
system/qemu
1
0
Fork 0
mirror of https://gitlab.com/qemu-project/qemu synced 2024-07-21 10:24:33 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: tweak kernel-doc for QEMU coding standards

Browse source 
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 <pbonzini@redhat.com>
This commit is contained in:
Paolo Bonzini 2019-10-29 17:22:44 +01:00
parent e2c546358f
commit 4cf4179441
1 changed files with 19 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
scripts/kernel-doc
View file

@ -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';