On Fri, Oct 02, 2020 at 07:43:09PM +0100, Peter Maydell wrote:
> On Fri, 2 Oct 2020 at 19:35, Eduardo Habkost <ehabk...@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 <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>
> > [...]
> > > > @@ -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
