On Thu, May 04, 2023 at 12:20:41PM +0300, Jani Nikula wrote:
> On Wed, 03 May 2023, Rodrigo Vivi <rodrigo.vivi@xxxxxxxxxx> 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@xxxxxxxxx>
> >> ---
> >> 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.
Anyway, let's move with this then:
Reviewed-by: Rodrigo Vivi <rodrigo.vivi@xxxxxxxxx>
>
> 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
