diff mbox series

[17/17] linux: v4l2-vp9.h: Fix kerneldoc

Message ID 20240126-gix-mtk-warnings-v1-17-eed7865fce18@chromium.org
State New
Headers
Series media: kerneldoc warnings |

Commit Message

Ricardo Ribalda Jan. 26, 2024, 11:16 p.m. UTC 
  Kerneldoc cannot understand arrays defined like
v4l2_frame_symbol_counts.

Adding an asterisk to the name does do the trick.

Disable the kerneldoc notation for now, it is already ignored:
https://docs.kernel.org/search.html?q=v4l2_vp9_frame_symbol_counts

include/media/v4l2-vp9.h:144: warning: Excess struct member 'partition' description in 'v4l2_vp9_frame_symbol_counts'
include/media/v4l2-vp9.h:144: warning: Excess struct member 'skip' description in 'v4l2_vp9_frame_symbol_counts'
include/media/v4l2-vp9.h:144: warning: Excess struct member 'intra_inter' description in 'v4l2_vp9_frame_symbol_counts'
include/media/v4l2-vp9.h:144: warning: Excess struct member 'tx32p' description in 'v4l2_vp9_frame_symbol_counts'
include/media/v4l2-vp9.h:144: warning: Excess struct member 'tx16p' description in 'v4l2_vp9_frame_symbol_counts'
include/media/v4l2-vp9.h:144: warning: Excess struct member 'tx8p' description in 'v4l2_vp9_frame_symbol_counts'
include/media/v4l2-vp9.h:144: warning: Excess struct member 'y_mode' description in 'v4l2_vp9_frame_symbol_counts'
include/media/v4l2-vp9.h:144: warning: Excess struct member 'uv_mode' description in 'v4l2_vp9_frame_symbol_counts'
include/media/v4l2-vp9.h:144: warning: Excess struct member 'comp' description in 'v4l2_vp9_frame_symbol_counts'
include/media/v4l2-vp9.h:144: warning: Excess struct member 'comp_ref' description in 'v4l2_vp9_frame_symbol_counts'
include/media/v4l2-vp9.h:144: warning: Excess struct member 'single_ref' description in 'v4l2_vp9_frame_symbol_counts'
include/media/v4l2-vp9.h:144: warning: Excess struct member 'mv_mode' description in 'v4l2_vp9_frame_symbol_counts'
include/media/v4l2-vp9.h:144: warning: Excess struct member 'filter' description in 'v4l2_vp9_frame_symbol_counts'
include/media/v4l2-vp9.h:144: warning: Excess struct member 'mv_joint' description in 'v4l2_vp9_frame_symbol_counts'
include/media/v4l2-vp9.h:144: warning: Excess struct member 'sign' description in 'v4l2_vp9_frame_symbol_counts'
include/media/v4l2-vp9.h:144: warning: Excess struct member 'classes' description in 'v4l2_vp9_frame_symbol_counts'
include/media/v4l2-vp9.h:144: warning: Excess struct member 'class0' description in 'v4l2_vp9_frame_symbol_counts'
include/media/v4l2-vp9.h:144: warning: Excess struct member 'bits' description in 'v4l2_vp9_frame_symbol_counts'
include/media/v4l2-vp9.h:144: warning: Excess struct member 'class0_fp' description in 'v4l2_vp9_frame_symbol_counts'
include/media/v4l2-vp9.h:144: warning: Excess struct member 'fp' description in 'v4l2_vp9_frame_symbol_counts'
include/media/v4l2-vp9.h:144: warning: Excess struct member 'class0_hp' description in 'v4l2_vp9_frame_symbol_counts'
include/media/v4l2-vp9.h:144: warning: Excess struct member 'hp' description in 'v4l2_vp9_frame_symbol_counts'

Signed-off-by: Ricardo Ribalda <ribalda@chromium.org>
---
 include/media/v4l2-vp9.h | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

Comments

Sakari Ailus Jan. 27, 2024, 9:57 a.m. UTC | #1 
Hi Ricardo,

On Fri, Jan 26, 2024 at 11:16:16PM +0000, Ricardo Ribalda wrote:
> Kerneldoc cannot understand arrays defined like
> v4l2_frame_symbol_counts.
> 
> Adding an asterisk to the name does do the trick.
> 
> Disable the kerneldoc notation for now, it is already ignored:
> https://docs.kernel.org/search.html?q=v4l2_vp9_frame_symbol_counts

Wouldn't it be nicer to fix kerneldoc instead? It might not be difficult at
all.

Feel free to, but I can also give it a try.
Hans Verkuil Feb. 5, 2024, 10:29 a.m. UTC | #2 
On 27/01/2024 10:57, Sakari Ailus wrote:
> Hi Ricardo,
> 
> On Fri, Jan 26, 2024 at 11:16:16PM +0000, Ricardo Ribalda wrote:
>> Kerneldoc cannot understand arrays defined like
>> v4l2_frame_symbol_counts.
>>
>> Adding an asterisk to the name does do the trick.
>>
>> Disable the kerneldoc notation for now, it is already ignored:
>> https://docs.kernel.org/search.html?q=v4l2_vp9_frame_symbol_counts
> 
> Wouldn't it be nicer to fix kerneldoc instead? It might not be difficult at
> all.
> 
> Feel free to, but I can also give it a try.
> 

It would be nice to have this fixed in kerneldoc itself. I'm holding this
patch back for two weeks to see if someone wants to work on kerneldoc.

If not, then I'll take this anyway to fix the noise in our build.

Note that while this header is indeed ignored in the documentation, that
is really more a bug and it would be nice to actually include this header
somewhere in our documentation. So fixing these kerneldoc warnings one way
or another is something that we should do.

Regards,

	Hans
Randy Dunlap Feb. 5, 2024, 10:39 a.m. UTC | #3 
On 2/5/24 02:29, Hans Verkuil wrote:
> On 27/01/2024 10:57, Sakari Ailus wrote:
>> Hi Ricardo,
>>
>> On Fri, Jan 26, 2024 at 11:16:16PM +0000, Ricardo Ribalda wrote:
>>> Kerneldoc cannot understand arrays defined like
>>> v4l2_frame_symbol_counts.
>>>
>>> Adding an asterisk to the name does do the trick.
>>>
>>> Disable the kerneldoc notation for now, it is already ignored:
>>> https://docs.kernel.org/search.html?q=v4l2_vp9_frame_symbol_counts
>>
>> Wouldn't it be nicer to fix kerneldoc instead? It might not be difficult at
>> all.
>>
>> Feel free to, but I can also give it a try.
>>
> 
> It would be nice to have this fixed in kerneldoc itself. I'm holding this
> patch back for two weeks to see if someone wants to work on kerneldoc.
> 
> If not, then I'll take this anyway to fix the noise in our build.
> 
> Note that while this header is indeed ignored in the documentation, that
> is really more a bug and it would be nice to actually include this header
> somewhere in our documentation. So fixing these kerneldoc warnings one way
> or another is something that we should do.
> 

It's just waiting for Jon to apply it: (from Sakari)

https://lore.kernel.org/all/20240131084934.191226-1-sakari.ailus@linux.intel.com/

Thanks.
Hans Verkuil Feb. 5, 2024, 10:44 a.m. UTC | #4 
On 05/02/2024 11:39, Randy Dunlap wrote:
> 
> 
> On 2/5/24 02:29, Hans Verkuil wrote:
>> On 27/01/2024 10:57, Sakari Ailus wrote:
>>> Hi Ricardo,
>>>
>>> On Fri, Jan 26, 2024 at 11:16:16PM +0000, Ricardo Ribalda wrote:
>>>> Kerneldoc cannot understand arrays defined like
>>>> v4l2_frame_symbol_counts.
>>>>
>>>> Adding an asterisk to the name does do the trick.
>>>>
>>>> Disable the kerneldoc notation for now, it is already ignored:
>>>> https://docs.kernel.org/search.html?q=v4l2_vp9_frame_symbol_counts
>>>
>>> Wouldn't it be nicer to fix kerneldoc instead? It might not be difficult at
>>> all.
>>>
>>> Feel free to, but I can also give it a try.
>>>
>>
>> It would be nice to have this fixed in kerneldoc itself. I'm holding this
>> patch back for two weeks to see if someone wants to work on kerneldoc.
>>
>> If not, then I'll take this anyway to fix the noise in our build.
>>
>> Note that while this header is indeed ignored in the documentation, that
>> is really more a bug and it would be nice to actually include this header
>> somewhere in our documentation. So fixing these kerneldoc warnings one way
>> or another is something that we should do.
>>
> 
> It's just waiting for Jon to apply it: (from Sakari)
> 
> https://lore.kernel.org/all/20240131084934.191226-1-sakari.ailus@linux.intel.com/

Ah, that patch was CCed to me but not to linux-media, and I only searched linux-media
for it so I missed it. Good news that this is fixed in the right place.

I marked this 17/17 patch as Obsoleted in patchwork.

Regards,

	Hans
Sakari Ailus Feb. 5, 2024, 10:53 a.m. UTC | #5 
Hi Hans,

On Mon, Feb 05, 2024 at 11:44:13AM +0100, Hans Verkuil wrote:
> On 05/02/2024 11:39, Randy Dunlap wrote:
> > 
> > 
> > On 2/5/24 02:29, Hans Verkuil wrote:
> >> On 27/01/2024 10:57, Sakari Ailus wrote:
> >>> Hi Ricardo,
> >>>
> >>> On Fri, Jan 26, 2024 at 11:16:16PM +0000, Ricardo Ribalda wrote:
> >>>> Kerneldoc cannot understand arrays defined like
> >>>> v4l2_frame_symbol_counts.
> >>>>
> >>>> Adding an asterisk to the name does do the trick.
> >>>>
> >>>> Disable the kerneldoc notation for now, it is already ignored:
> >>>> https://docs.kernel.org/search.html?q=v4l2_vp9_frame_symbol_counts
> >>>
> >>> Wouldn't it be nicer to fix kerneldoc instead? It might not be difficult at
> >>> all.
> >>>
> >>> Feel free to, but I can also give it a try.
> >>>
> >>
> >> It would be nice to have this fixed in kerneldoc itself. I'm holding this
> >> patch back for two weeks to see if someone wants to work on kerneldoc.
> >>
> >> If not, then I'll take this anyway to fix the noise in our build.
> >>
> >> Note that while this header is indeed ignored in the documentation, that
> >> is really more a bug and it would be nice to actually include this header
> >> somewhere in our documentation. So fixing these kerneldoc warnings one way
> >> or another is something that we should do.
> >>
> > 
> > It's just waiting for Jon to apply it: (from Sakari)
> > 
> > https://lore.kernel.org/all/20240131084934.191226-1-sakari.ailus@linux.intel.com/
> 
> Ah, that patch was CCed to me but not to linux-media, and I only searched linux-media
> for it so I missed it. Good news that this is fixed in the right place.

My bad, somehow I missed linux-media from the distribution. :-(

> 
> I marked this 17/17 patch as Obsoleted in patchwork.

Thank you!
diff mbox series

Patch

diff --git a/include/media/v4l2-vp9.h b/include/media/v4l2-vp9.h
index 05478ad6d4ab..f0d80273bd61 100644
--- a/include/media/v4l2-vp9.h
+++ b/include/media/v4l2-vp9.h
@@ -83,7 +83,11 @@  struct v4l2_vp9_frame_context {
 	struct v4l2_vp9_frame_mv_context mv;
 };
 
-/**
+/*
+ * NOTE: This is not a kerneldoc, because the (*name) notation confuses the
+ *	 parser.
+ */
+/*
  * struct v4l2_vp9_frame_symbol_counts - pointers to arrays of symbol counts
  *
  * @partition: partition counts.