[PATCH] drm: improve kernel-docs in drm_mode.h

[Daniel Vetter]

On Thu, Nov 19, 2020 at 10:03:20AM +0000, Simon Ser wrote:
> - Remove duplicate doc-comments for struct members
> - Add missing @member markers for in-line member comments
> 
> Signed-off-by: Simon Ser <contact at emersion.fr>
> Cc: Daniel Vetter <daniel at ffwll.ch>

Acked-by: Daniel Vetter <daniel.vetter at ffwll.ch>

> ---
>  include/uapi/drm/drm_mode.h | 66 ++++++++++++++++++-------------------
>  1 file changed, 32 insertions(+), 34 deletions(-)
> 
> diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h
> index 5ad10ab2a577..f29c1d37be67 100644
> --- a/include/uapi/drm/drm_mode.h
> +++ b/include/uapi/drm/drm_mode.h
> @@ -905,24 +905,23 @@ struct drm_format_modifier {
>  
>  /**
>   * struct drm_mode_create_blob - Create New block property
> - * @data: Pointer to data to copy.
> - * @length: Length of data to copy.
> - * @blob_id: new property ID.
> + *
>   * Create a new 'blob' data property, copying length bytes from data pointer,
>   * and returning new blob ID.
>   */
>  struct drm_mode_create_blob {
> -	/** Pointer to data to copy. */
> +	/** @data: Pointer to data to copy. */
>  	__u64 data;
> -	/** Length of data to copy. */
> +	/** @length: Length of data to copy. */
>  	__u32 length;
> -	/** Return: new property ID. */
> +	/** @blob_id: Return: new property ID. */
>  	__u32 blob_id;
>  };
>  
>  /**
>   * struct drm_mode_destroy_blob - Destroy user blob
>   * @blob_id: blob_id to destroy
> + *
>   * Destroy a user-created blob property.
>   *
>   * User-space can release blobs as soon as they do not need to refer to them by
> @@ -937,36 +936,32 @@ struct drm_mode_destroy_blob {
>  
>  /**
>   * struct drm_mode_create_lease - Create lease
> - * @object_ids: Pointer to array of object ids.
> - * @object_count: Number of object ids.
> - * @flags: flags for new FD.
> - * @lessee_id: unique identifier for lessee.
> - * @fd: file descriptor to new drm_master file.
> + *
>   * Lease mode resources, creating another drm_master.
>   */
>  struct drm_mode_create_lease {
> -	/** Pointer to array of object ids (__u32) */
> +	/** @object_ids: Pointer to array of object ids (__u32) */
>  	__u64 object_ids;
> -	/** Number of object ids */
> +	/** @object_count: Number of object ids */
>  	__u32 object_count;
> -	/** flags for new FD (O_CLOEXEC, etc) */
> +	/** @flags: flags for new FD (O_CLOEXEC, etc) */
>  	__u32 flags;
>  
> -	/** Return: unique identifier for lessee. */
> +	/** @lessee_id: Return: unique identifier for lessee. */
>  	__u32 lessee_id;
> -	/** Return: file descriptor to new drm_master file */
> +	/** @fd: Return: file descriptor to new drm_master file */
>  	__u32 fd;
>  };
>  
>  /**
>   * struct drm_mode_list_lessees - List lessees
> - * @count_lessees: Number of lessees.
> - * @pad: pad.
> - * @lessees_ptr: Pointer to lessess.
> - * List lesses from a drm_master
> + *
> + * List lesses from a drm_master.
>   */
>  struct drm_mode_list_lessees {
> -	/** Number of lessees.
> +	/**
> +	 * @count_lessees: Number of lessees.
> +	 *
>  	 * On input, provides length of the array.
>  	 * On output, provides total number. No
>  	 * more than the input number will be written
> @@ -974,23 +969,26 @@ struct drm_mode_list_lessees {
>  	 * the size and then the data.
>  	 */
>  	__u32 count_lessees;
> +	/** @pad: Padding. */
>  	__u32 pad;
>  
> -	/** Pointer to lessees.
> -	 * pointer to __u64 array of lessee ids
> +	/**
> +	 * @lessees_ptr: Pointer to lessees.
> +	 *
> +	 * Pointer to __u64 array of lessee ids
>  	 */
>  	__u64 lessees_ptr;
>  };
>  
>  /**
>   * struct drm_mode_get_lease - Get Lease
> - * @count_objects: Number of leased objects.
> - * @pad: pad.
> - * @objects_ptr: Pointer to objects.
> - * Get leased objects
> + *
> + * Get leased objects.
>   */
>  struct drm_mode_get_lease {
> -	/** Number of leased objects.
> +	/**
> +	 * @count_objects: Number of leased objects.
> +	 *
>  	 * On input, provides length of the array.
>  	 * On output, provides total number. No
>  	 * more than the input number will be written
> @@ -998,22 +996,22 @@ struct drm_mode_get_lease {
>  	 * the size and then the data.
>  	 */
>  	__u32 count_objects;
> +	/** @pad: Padding. */
>  	__u32 pad;
>  
> -	/** Pointer to objects.
> -	 * pointer to __u32 array of object ids
> +	/**
> +	 * @objects_ptr: Pointer to objects.
> +	 *
> +	 * Pointer to __u32 array of object ids.
>  	 */
>  	__u64 objects_ptr;
>  };
>  
>  /**
>   * struct drm_mode_revoke_lease - Revoke lease
> - * @lessee_id: Unique ID of lessee.
> - * Revoke lease
>   */
>  struct drm_mode_revoke_lease {
> -	/** Unique ID of lessee
> -	 */
> +	/** @lessee_id: Unique ID of lessee */
>  	__u32 lessee_id;
>  };
>  
> -- 
> 2.29.2
> 
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch