| Message ID | a2a81f9ee78591def0534c81a63dbc652c44bbd3.1683041799.git.jani.nikula@intel.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | drm/i915: fix kernel-doc warnings, enable kernel-doc -Werror | expand |
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@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. +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 >
On Wed, 03 May 2023, Rodrigo Vivi <rodrigo.vivi@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@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. 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 >>
On Thu, May 04, 2023 at 12:20:41PM +0300, Jani Nikula wrote: > On Wed, 03 May 2023, Rodrigo Vivi <rodrigo.vivi@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@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. Anyway, let's move with this then: Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com> > > 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
On Thu, 04 May 2023, Rodrigo Vivi <rodrigo.vivi@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@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@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@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
On Thu, 04 May 2023, Rodrigo Vivi <rodrigo.vivi@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@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@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. > > Anyway, let's move with this then: > > Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com> Thanks, pushed to drm-intel-gt-next, as well as the other ones. BR, 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
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 * * Note that if this function is part of a ww transaction, and * if returns -EDEADLK for one of the objects, it may be
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@intel.com> --- drivers/gpu/drm/i915/gem/i915_gem_region.h | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-)