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

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

[Tomi Valkeinen]

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_*
  */
 struct v4l2_subdev_fh {
 	struct v4l2_fh vfh;
-- 
2.34.1

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

[Laurent Pinchart]

Hi Tomi,

Thank you for the patch.

On Tue, Apr 18, 2023 at 01:59:24PM +0300, Tomi Valkeinen wrote:
> Add missing kernel doc for the new 'client_caps' field in struct
> v4l2_subdev_fh.
> 
> Signed-off-by: Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>

Reviewed-by: Laurent Pinchart <laurent.pinchart@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_*
>   */
>  struct v4l2_subdev_fh {
>  	struct v4l2_fh vfh;

-- 
Regards,

Laurent Pinchart

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

[Sakari Ailus]

On Tue, Apr 18, 2023 at 05:33:30PM +0300, Laurent Pinchart wrote:
> Hi Tomi,
> 
> Thank you for the patch.
> 
> On Tue, Apr 18, 2023 at 01:59:24PM +0300, Tomi Valkeinen wrote:
> > Add missing kernel doc for the new 'client_caps' field in struct
> > v4l2_subdev_fh.
> > 
> > Signed-off-by: Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
> 
> Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

Thanks!

Added:

Fixes: f57fa2959244 ("media: v4l2-subdev: Add new ioctl for client capabilities")

-- 
Sakari Ailus

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

[Mauro Carvalho Chehab]

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!

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

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;

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

[Tomi Valkeinen]

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

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

[Sakari Ailus]

Hi Mauro,

On Thu, May 18, 2023 at 09:41:31AM +0100, 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!

I don't get a warning with this patch. Also the documentation is rendered
correctly. Which sphinx version do you have?

$ sphinx-build --version
sphinx-build 3.4.3

-- 
Sakari Ailus