From 4cf41794411f91453e19da88ecb7e806a831abf8 Mon Sep 17 00:00:00 2001 From: Paolo Bonzini Date: Tue, 29 Oct 2019 17:22:44 +0100 Subject: docs: tweak kernel-doc for QEMU coding standards 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 --- scripts/kernel-doc | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) (limited to 'scripts') 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'; -- cgit v1.2.3