Re: [PATCH] media: v4l2-subdev: Fix missing kerneldoc for client_caps

[Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>]

On 18/05/2023 11:41, Mauro Carvalho Chehab wrote:
> Em Tue, 18 Apr 2023 13:59:24 +0300
> Tomi Valkeinen <tomi.valkeinen@ideasonboard.com> escreveu:
> 
>> Add missing kernel doc for the new 'client_caps' field in struct
>> v4l2_subdev_fh.
>>
>> Signed-off-by: Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
>> ---
>>   include/media/v4l2-subdev.h | 1 +
>>   1 file changed, 1 insertion(+)
>>
>> diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
>> index cfd19e72d0fc..9d0a6a993fb0 100644
>> --- a/include/media/v4l2-subdev.h
>> +++ b/include/media/v4l2-subdev.h
>> @@ -1119,6 +1119,7 @@ struct v4l2_subdev {
>>    * @vfh: pointer to &struct v4l2_fh
>>    * @state: pointer to &struct v4l2_subdev_state
>>    * @owner: module pointer to the owner of this file handle
>> + * @client_caps: bitmask of V4L2_SUBDEV_CLIENT_CAP_*
> 
> Did you actually check this patch? Adding an asterisk at the end
> should hit a Sphinx warning, as asterisk is the italic markup.
> So, it seems to me that this patch is actually replacing one warning
> by another one!

htmldocs compiles fine for me, without warnings (from this piece of 
code), and the resulting html looks ok. pdfdocs doesn't compile, but I 
have no clue why it fails, and it fails without this patch too.

> Also, it is not pointing the patch this was supposed to be fixing.

That's true.

> Btw, I actually did a fix for it already, while I was working to fix
> some issues on Jenkins. See below. If you're ok with that, please add
> your A-B or R-B. Otherwise, submit another one, after testing that
> Sphinx won't be printing an additional warning.
> 
> Regards,
> Mauro
> 
> ---
> 
> [PATCH] media: v4l2-subdev.h: document client_caps at struct v4l2_subdev_fh
> 
> Gets rid of this documentation warning:
> 
> 	./include/media/v4l2-subdev.h:1130: warning: Function parameter or member 'client_caps' not described in 'v4l2_subdev_fh'
> 
> By adding a documentation about such new field.
> 
> Fixes: f57fa2959244 ("media: v4l2-subdev: Add new ioctl for client capabilities")
> Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> 
> diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
> index cfd19e72d0fc..62362da0d604 100644
> --- a/include/media/v4l2-subdev.h
> +++ b/include/media/v4l2-subdev.h
> @@ -1119,6 +1119,9 @@ struct v4l2_subdev {
>    * @vfh: pointer to &struct v4l2_fh
>    * @state: pointer to &struct v4l2_subdev_state
>    * @owner: module pointer to the owner of this file handle
> + * @client_caps:
> + *	client capabilities to inform the kernel of the behavior
> + *	of the client as set by VIDIOC_SUBDEV_S_CLIENT_CAP.
>    */
>   struct v4l2_subdev_fh {
>   	struct v4l2_fh vfh;

I'm fine with this version too.

Reviewed-by: Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>

  Tomi