Re: [PATCH 3/3] docs/doxygen: doxygen documentation for grant_table.h

[Stefano Stabellini <sstabellini@kernel.org>]

On Tue, 6 Apr 2021, Jan Beulich wrote:
> On 06.04.2021 12:36, Luca Fancellu wrote:
> > Modification to include/public/grant_table.h:
> > 
> > 1) Change anonymous structure to be named structure,
> >    because doxygen can't deal with them.
> 
> Especially in the form presented (adding further name space clutter
> for consumers to fall over) I object to this, most notably ...
> 
> > @@ -584,7 +599,7 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_swap_grant_ref_t);
> >   * page granted to the calling domain by a foreign domain.
> >   */
> >  struct gnttab_cache_flush {
> > -    union {
> > +    union a {
> 
> ... this one.

Hi Jan,

It is unfortunate that none of these tools support anonymous structs or
unions well. (You might recall we also had issues with the older
kernel-doc series too, although a bit different.)

It is difficult to provide a good name here, a suggestion would be more
than welcome. I agree with you that calling it "a" is a bad idea: "a"
becomes a globally-visible union name.

Maybe we could call it: StructName_MemberName, so in this case:

  union gnttab_cache_flush_a

It makes sure it is unique and doesn't risk clashing with anything else.
We can follow this pattern elsewhere as well.

Any better suggestions?