Re: [PATCH 06/14] kernel-doc: public/grant_table.h

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

On Fri, 7 Aug 2020, Jan Beulich wrote:
> On 07.08.2020 01:49, Stefano Stabellini wrote:
> > @@ -108,56 +107,66 @@
> >   *  Use SMP-safe bit-setting instruction.
> >   */
> >  
> > -/*
> > +/**
> > + * typedef
> >   * Reference to a grant entry in a specified domain's grant table.
> >   */
> >  typedef uint32_t grant_ref_t;
> 
> In the comment, did you mean grant_ref_t?

Yes, I'll fix it.


> > -/*
> > +/**
> > + * DOC: grant table
> > + *
> >   * A grant table comprises a packed array of grant entries in one or more
> >   * page frames shared between Xen and a guest.
> >   * [XEN]: This field is written by Xen and read by the sharing guest.
> >   * [GST]: This field is written by the guest and read by Xen.
> >   */
> >  
> > -/*
> > - * Version 1 of the grant table entry structure is maintained purely
> > - * for backwards compatibility.  New guests should use version 2.
> > - */
> >  #if __XEN_INTERFACE_VERSION__ < 0x0003020a
> >  #define grant_entry_v1 grant_entry
> >  #define grant_entry_v1_t grant_entry_t
> >  #endif
> > +/**
> > + * struct grant_entry_v1
> > + *
> > + * Version 1 of the grant table entry structure is maintained purely
> > + * for backwards compatibility.  New guests should use version 2.
> > + */
> 
> I realize content changes aren't intended, but here I can't resist
> recommending to drop the second sentence at this occasion.

OK


> > +/**
> > + * DOC: Values for error status returns. All errors are -ve.
> > + *
> > + *
> > + * - GNTST_okay: Normal return.
> 
> Nit: Why two blank comment lines above?

A small mistake, I'll fix it.