Re: [Intel-gfx] [PATCH v2 08/39] drm/i915: gem: fix some Kernel-doc issues

["Das, Nirmoy" <nirmoy.das@intel.com>]

[-- Attachment #1: Type: text/plain, Size: 7936 bytes --]


On 7/13/2022 10:11 AM, Mauro Carvalho Chehab wrote:
> There are several trivial issueson kernel-doc markups at gem:
>
> 	drivers/gpu/drm/i915/gem/i915_gem_create.c:146: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> 	drivers/gpu/drm/i915/gem/i915_gem_create.c:217: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> 	drivers/gpu/drm/i915/gem/i915_gem_create.c:401: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> 	drivers/gpu/drm/i915/gem/i915_gem_domain.c:116: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> 	drivers/gpu/drm/i915/gem/i915_gem_domain.c:177: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> 	drivers/gpu/drm/i915/gem/i915_gem_domain.c:262: warning: expecting prototype for Changes the cache(). Prototype was for i915_gem_object_set_cache_level() instead
> 	drivers/gpu/drm/i915/gem/i915_gem_domain.c:456: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> 	drivers/gpu/drm/i915/gem/i915_gem_domain.c:500: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> 	drivers/gpu/drm/i915/gem/i915_gem_object.h:110: warning: Function parameter or member 'file' not described in 'i915_gem_object_lookup_rcu'
> 	drivers/gpu/drm/i915/gem/i915_gem_object.h:110: warning: Excess function parameter 'filp' description in 'i915_gem_object_lookup_rcu'
> 	drivers/gpu/drm/i915/gem/i915_gem_region.h:35: warning: Function parameter or member 'process_obj' not described in 'i915_gem_apply_to_region_ops'
> 	drivers/gpu/drm/i915/gem/i915_gem_wait.c:130: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>
> Caused by:
> 	- lack of function name at the kernel-doc markup;
> 	- renamed parameters.
>
> Address them.
>
> Signed-off-by: Mauro Carvalho Chehab<mchehab@kernel.org>

|Reviewed-by: Nirmoy Das<nirmoy.das@intel.com>|

> ---
>
> 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@kernel.org/
>
>   drivers/gpu/drm/i915/gem/i915_gem_create.c |  8 +++++---
>   drivers/gpu/drm/i915/gem/i915_gem_domain.c | 17 +++++++++++------
>   drivers/gpu/drm/i915/gem/i915_gem_object.h |  2 +-
>   drivers/gpu/drm/i915/gem/i915_gem_wait.c   |  2 +-
>   4 files changed, 18 insertions(+), 11 deletions(-)
>
> diff --git a/drivers/gpu/drm/i915/gem/i915_gem_create.c b/drivers/gpu/drm/i915/gem/i915_gem_create.c
> index 33673fe7ee0a..8cb2eb092031 100644
> --- a/drivers/gpu/drm/i915/gem/i915_gem_create.c
> +++ b/drivers/gpu/drm/i915/gem/i915_gem_create.c
> @@ -143,7 +143,8 @@ __i915_gem_object_create_user_ext(struct drm_i915_private *i915, u64 size,
>   }
>   
>   /**
> - * Creates a new object using the same path as DRM_I915_GEM_CREATE_EXT
> + * __i915_gem_object_create_user - Creates a new object using the same path
> + *	as DRM_I915_GEM_CREATE_EXT
>    * @i915: i915 private
>    * @size: size of the buffer, in bytes
>    * @placements: possible placement regions, in priority order
> @@ -214,7 +215,7 @@ i915_gem_dumb_create(struct drm_file *file,
>   }
>   
>   /**
> - * Creates a new mm object and returns a handle to it.
> + * i915_gem_create_ioctl - Creates a new mm object and returns a handle to it.
>    * @dev: drm device pointer
>    * @data: ioctl data blob
>    * @file: drm file pointer
> @@ -398,7 +399,8 @@ static const i915_user_extension_fn create_extensions[] = {
>   };
>   
>   /**
> - * Creates a new mm object and returns a handle to it.
> + * i915_gem_create_ext_ioctl - Creates a new mm object and returns a handle
> + *	to it.
>    * @dev: drm device pointer
>    * @data: ioctl data blob
>    * @file: drm file pointer
> diff --git a/drivers/gpu/drm/i915/gem/i915_gem_domain.c b/drivers/gpu/drm/i915/gem/i915_gem_domain.c
> index 1674b0c5802b..49d7841ba979 100644
> --- a/drivers/gpu/drm/i915/gem/i915_gem_domain.c
> +++ b/drivers/gpu/drm/i915/gem/i915_gem_domain.c
> @@ -113,7 +113,8 @@ void i915_gem_object_flush_if_display_locked(struct drm_i915_gem_object *obj)
>   }
>   
>   /**
> - * Moves a single object to the WC read, and possibly write domain.
> + * i915_gem_object_set_to_wc_domain - Moves a single object to the WC read,
> + *	and possibly write domain.
>    * @obj: object to act on
>    * @write: ask for write access or read only
>    *
> @@ -174,7 +175,8 @@ i915_gem_object_set_to_wc_domain(struct drm_i915_gem_object *obj, bool write)
>   }
>   
>   /**
> - * Moves a single object to the GTT read, and possibly write domain.
> + * i915_gem_object_set_to_gtt_domain - Moves a single object to the GTT read,
> + *	and possibly write domain.
>    * @obj: object to act on
>    * @write: ask for write access or read only
>    *
> @@ -243,7 +245,8 @@ i915_gem_object_set_to_gtt_domain(struct drm_i915_gem_object *obj, bool write)
>   }
>   
>   /**
> - * Changes the cache-level of an object across all VMA.
> + * i915_gem_object_set_cache_level - Changes the cache-level of an object
> + *	across all VMA.
>    * @obj: object to act on
>    * @cache_level: new cache level to set for the object
>    *
> @@ -453,7 +456,8 @@ i915_gem_object_pin_to_display_plane(struct drm_i915_gem_object *obj,
>   }
>   
>   /**
> - * Moves a single object to the CPU read, and possibly write domain.
> + * i915_gem_object_set_to_cpu_domain - Moves a single object to the CPU read,
> + *	and possibly write domain.
>    * @obj: object to act on
>    * @write: requesting write or read-only access
>    *
> @@ -497,8 +501,9 @@ i915_gem_object_set_to_cpu_domain(struct drm_i915_gem_object *obj, bool write)
>   }
>   
>   /**
> - * Called when user space prepares to use an object with the CPU, either
> - * through the mmap ioctl's mapping or a GTT mapping.
> + * i915_gem_set_domain_ioctl - Called when user space prepares to use an
> + *	object with the CPU, either through the mmap ioctl's mapping or a
> + *	GTT mapping.
>    * @dev: drm device
>    * @data: ioctl data blob
>    * @file: drm file
> diff --git a/drivers/gpu/drm/i915/gem/i915_gem_object.h b/drivers/gpu/drm/i915/gem/i915_gem_object.h
> index 6f0a3ce35567..222608df66df 100644
> --- a/drivers/gpu/drm/i915/gem/i915_gem_object.h
> +++ b/drivers/gpu/drm/i915/gem/i915_gem_object.h
> @@ -96,7 +96,7 @@ __i915_gem_object_unset_pages(struct drm_i915_gem_object *obj);
>   
>   /**
>    * i915_gem_object_lookup_rcu - look up a temporary GEM object from its handle
> - * @filp: DRM file private date
> + * @file: DRM file private date
>    * @handle: userspace handle
>    *
>    * Returns:
> diff --git a/drivers/gpu/drm/i915/gem/i915_gem_wait.c b/drivers/gpu/drm/i915/gem/i915_gem_wait.c
> index e6e01c2a74a6..4a33ad2d122b 100644
> --- a/drivers/gpu/drm/i915/gem/i915_gem_wait.c
> +++ b/drivers/gpu/drm/i915/gem/i915_gem_wait.c
> @@ -161,7 +161,7 @@ i915_gem_object_wait_priority(struct drm_i915_gem_object *obj,
>   }
>   
>   /**
> - * Waits for rendering to the object to be completed
> + * i915_gem_object_wait - Waits for rendering to the object to be completed
>    * @obj: i915 gem object
>    * @flags: how to wait (under a lock, for all rendering or just for writes etc)
>    * @timeout: how long to wait
Intel Deutschland GmbH
Registered Address: Am Campeon 10, 85579 Neubiberg, Germany
Tel: +49 89 99 8853-0, www.intel.de <http://www.intel.de>
Managing Directors: Christin Eisenschmid, Sharon Heck, Tiffany Doon Silva  
Chairperson of the Supervisory Board: Nicole Lau
Registered Office: Munich
Commercial Register: Amtsgericht Muenchen HRB 186928

[-- Attachment #2: Type: text/html, Size: 8589 bytes --]