On Fri, 29 Nov 2019 at 14:02, Paolo Bonzini <pbonz...@redhat.com> wrote:
>
> 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 <pbonz...@redhat.com>
> ---
> 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]+)';
perlre(1) says that \w includes _' so I think
'[_\w]' is a funny way of writing '\w', but on
the other hand it's in the existing code too...
> +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*//;
These two bits seem to be a third thing not mentioned
in the commit message -- permitting either colon or
hyphen in the "Thing: short description" introductory line,
where kernel style insists on a hyphen.
(You could make the argument that this is an unnecessary
drift from the kernel-doc style and we should just fix
up all those colons...)
> @@ -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';
The match for 'type name' is pretty wide but I guess
we can find out through experience if we need to narrow it.
thanks
-- PMM
