[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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



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?



 


Rackspace

Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.