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

[Eduardo Habkost <ehabkost@redhat.com>]

On Fri, Oct 02, 2020 at 07:43:09PM +0100, Peter Maydell wrote:
> On Fri, 2 Oct 2020 at 19:35, Eduardo Habkost <ehabkost@redhat.com> wrote:
> >
> > On Mon, Dec 02, 2019 at 06:01:16PM +0000, Peter Maydell wrote:
> > > 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>
> > [...]
> > > > @@ -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.
> >
> > This change seems to make it impossible to document any macros
> > with uppercase names.
> >
> > (for example, most of the macros in object.h are not included in
> > the generated docs)
> >
> > What exactly is the purpose of the hunk above?
> 
> It's so that QEMU's bare type names like MemoryRegionSection get
> recognized as being types. Kernel naming style always
> prefers to say "struct MemoryRegionSection" where we use the
> typedef and say "MemoryRegionSection", which is why the upstream
> kernel-doc doesn't care about this. IIRC, without it, doc comments
> which reference a type like '#TypeName' like:
> 
>      * @log_sync:
>      *
>      * Called by memory_region_snapshot_and_clear_dirty() and
>      * memory_global_dirty_log_sync(), before accessing QEMU's "official"
>      * copy of the dirty memory bitmap for a #MemoryRegionSection.
>      *
> 
> don't correctly render the typename into a link to the
> struct definition.

This is not the code that parses "#MemoryRegionSection", it is
the code that parses:

/**
 * MemoryRegionSection: describes a fragment of a #MemoryRegion
   ^^^^^^^ this line


-- 
Eduardo