Re: [Intel-gfx] [PATCH v2 19/39] drm/i915: i915_gem_region.h: fix i915_gem_apply_to_region_ops doc

[Rodrigo Vivi]

On Wed, Jul 13, 2022 at 09:12:07AM +0100, Mauro Carvalho Chehab wrote:
> The kernel-doc markup for i915_gem_apply_to_region_ops() has some
> issues:
> 
> 1. The field should be marked as @process_obj;
> 2. The callback parameters aren't document properly, as sphinx
>    will consider them to be placed at the wrong place.
> 
> Fix (1) and change the way the parameters are described, using
> a list, in order for it to be properly parsed during documentation
> build time.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@xxxxxxxxxx>

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@xxxxxxxxx>
> ---
> 
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/cover.1657699522.git.mchehab@xxxxxxxxxx/
> 
>  drivers/gpu/drm/i915/gem/i915_gem_region.h | 8 +++++---
>  1 file changed, 5 insertions(+), 3 deletions(-)
> 
> diff --git a/drivers/gpu/drm/i915/gem/i915_gem_region.h b/drivers/gpu/drm/i915/gem/i915_gem_region.h
> index 2dfcc41c0170..b0134bf4b1b7 100644
> --- a/drivers/gpu/drm/i915/gem/i915_gem_region.h
> +++ b/drivers/gpu/drm/i915/gem/i915_gem_region.h
> @@ -22,9 +22,11 @@ struct i915_gem_apply_to_region;
>   */
>  struct i915_gem_apply_to_region_ops {
>  	/**
> -	 * process_obj - Process the current object
> -	 * @apply: Embed this for private data.
> -	 * @obj: The current object.
> +	 * @process_obj: Callback function to process the current object
> +	 * it requires two arguments:
> +	 *
> +	 * - @apply: Embed this for private data.
> +	 * - @obj: The current object.
>  	 *
>  	 * Note that if this function is part of a ww transaction, and
>  	 * if returns -EDEADLK for one of the objects, it may be
> -- 
> 2.36.1
>