[Intel-xe] [PATCH 1/2] drm/xe/uapi: silence kernel-doc errors

[Francois Dugast]

On Fri, Jun 23, 2023 at 12:29:21PM +0100, Matthew Auld wrote:
> ./include/uapi/drm/xe_drm.h:263: warning: Function parameter or member
> 'gts' not described in 'drm_xe_query_gts'
> 
> ./include/uapi/drm/xe_drm.h:854: WARNING: Inline emphasis start-string
> without end-string.
> 
> With the idea to include the uapi file in the pre-merge CI hooks when
> building the kernel-doc, so first make sure it's clean.
> 
> Signed-off-by: Matthew Auld <matthew.auld at intel.com>
> Cc: Francois Dugast <francois.dugast at intel.com>
> Cc: Lucas De Marchi <lucas.demarchi at intel.com>
> ---
>  include/uapi/drm/xe_drm.h | 9 +++++----
>  1 file changed, 5 insertions(+), 4 deletions(-)
> 
> diff --git a/include/uapi/drm/xe_drm.h b/include/uapi/drm/xe_drm.h
> index 432bd87ca401..5da6a04bb478 100644
> --- a/include/uapi/drm/xe_drm.h
> +++ b/include/uapi/drm/xe_drm.h
> @@ -228,7 +228,7 @@ struct drm_xe_query_config {
>  	__u64 info[];
>  };
>  
> -/**
> +/*

There are multiple occurrences of this in this file, which seems ok to
me. Is this one particular somehow? If it needs to be fixed why not the
others?

The commit message refers to a missing description line 263, that is 
attribute gts of struct drm_xe_query_gts. Is that not the real issue?

    	} gts[];

Francois

>   * struct drm_xe_query_gts - describe GTs
>   *
>   * If a query is made with a struct drm_xe_device_query where .query
> @@ -242,7 +242,7 @@ struct drm_xe_query_gts {
>  	/** @pad: MBZ */
>  	__u32 pad;
>  
> -	/*
> +	/* TODO: convert to proper kernel-doc.
>  	 * TODO: Perhaps info about every mem region relative to this GT? e.g.
>  	 * bandwidth between this GT and remote region?
>  	 */
> @@ -852,8 +852,9 @@ struct drm_xe_mmio {
>   * struct drm_xe_wait_user_fence - wait user fence
>   *
>   * Wait on user fence, XE will wakeup on every HW engine interrupt in the
> - * instances list and check if user fence is complete:
> - * (*addr & MASK) OP (VALUE & MASK)
> + * instances list and check if user fence is complete::
> + *
> + *	(*addr & MASK) OP (VALUE & MASK)
>   *
>   * Returns to user on user fence completion or timeout.
>   */
> -- 
> 2.41.0
>