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

[Peter Maydell]

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.

thanks
-- PMM