[Intel-gfx] [PATCH 10/24] drm/i915/gem: fix function pointer member kernel-doc

[Jani Nikula]

On Thu, 04 May 2023, Rodrigo Vivi <rodrigo.vivi at kernel.org> wrote:
> On Thu, May 04, 2023 at 12:20:41PM +0300, Jani Nikula wrote:
>> On Wed, 03 May 2023, Rodrigo Vivi <rodrigo.vivi at kernel.org> wrote:
>> > On Tue, May 02, 2023 at 06:37:27PM +0300, Jani Nikula wrote:
>> >> You can't document function pointer member as functions.
>> >>
>> >> drivers/gpu/drm/i915/gem/i915_gem_region.h:25: warning: Incorrect use of kernel-doc format:          * process_obj - Process the current object
>> >> 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'
>> >>
>> >> Signed-off-by: Jani Nikula <jani.nikula at intel.com>
>> >> ---
>> >>  drivers/gpu/drm/i915/gem/i915_gem_region.h | 4 +---
>> >>  1 file changed, 1 insertion(+), 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..8a7650b27cc2 100644
>> >> --- a/drivers/gpu/drm/i915/gem/i915_gem_region.h
>> >> +++ b/drivers/gpu/drm/i915/gem/i915_gem_region.h
>> >> @@ -22,9 +22,7 @@ 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: Process the current object
>> >
>> > hmm...
>> > looking to the process_obj itself I wonder if we don't have a better way
>> > to document these function pointer arguments that could be acceptable
>> > instead of simply removing them.
>> 
>> The alternative is pretty much to document the parameters in plain text
>> or some mild rst formatting that's not specifically kernel-doc parameter
>> documentation.
>
> :( something that could be improved in the overall infra since it is a useful
> info.

I don't disagree per se, but I wouldn't touch kernel-doc the script with
a ten-foot pole anymore.

>
> Anyway, let's move with this then:
>
> Reviewed-by: Rodrigo Vivi <rodrigo.vivi at intel.com>

Thanks,
Jani.

>
>
>> 
>> BR,
>> Jani.
>> 
>> >
>> > +Mauro in case he has some idea.
>> >
>> > and the declaration for reference:
>> >
>> >  int (*process_obj)(struct i915_gem_apply_to_region *apply,
>> >                            struct drm_i915_gem_object *obj);
>> >
>> >>  	 *
>> >>  	 * Note that if this function is part of a ww transaction, and
>> >>  	 * if returns -EDEADLK for one of the objects, it may be
>> >> --
>> >> 2.39.2
>> >>
>> 
>> -- 
>> Jani Nikula, Intel Open Source Graphics Center

-- 
Jani Nikula, Intel Open Source Graphics Center