Re: [PATCH 2/8] docs: tweak kernel-doc for QEMU coding standards

[Peter Maydell <peter.maydell@linaro.org>]

On Fri, 29 Nov 2019 at 14:02, Paolo Bonzini <pbonzini@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 <pbonzini@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