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

[Jan Beulich <jbeulich@xxxxxxxx>]

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?

> -/*
> +/**
> + * 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.

> +/**
> + * DOC: Values for error status returns. All errors are -ve.
> + *
> + *
> + * - GNTST_okay: Normal return.

Nit: Why two blank comment lines above?

Jan