[RFC 1/1] kernel-doc: Support arrays of pointers struct fields

[RFC 1/1] kernel-doc: Support arrays of pointers struct fields

[Sakari Ailus]

In a rather unusual arrangement in include/media/v4l2-vp9.h struct
v4l2_vp9_frame_symbol_counts has fields that are arrays of pointers, not a
pointer to an array, which is what's usually done.

Add support for such arrays of pointers to kernel-doc.

Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
---
Hi Ricardo,

I tried to ram it together with processing the rest but it seemed
to complicate processing the usual fields.

 scripts/kernel-doc | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index e8aefd258a29..728b1ffc0478 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1509,6 +1509,15 @@ sub create_parameterlist($$$$) {
 	    $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
 	    save_struct_actual($param);
 	    push_parameter($param, $type, $arg, $file, $declaration_name);
+	} elsif ($arg =~ m/\(.+\)\s*\[/) {
+	    # array-of-pointers
+	    $arg =~ tr/#/,/;
+	    $arg =~ m/[^\(]+\(\s*\*\s*([\w\[\]\.]*?)\s*(\s*\[\s*[\w]+\s*\]\s*)*\)/;
+	    $param = $1;
+	    $type = $arg;
+	    $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
+	    save_struct_actual($param);
+	    push_parameter($param, $type, $arg, $file, $declaration_name);
 	} elsif ($arg) {
 	    $arg =~ s/\s*:\s*/:/g;
 	    $arg =~ s/\s*\[/\[/g;
-- 
2.39.2

Re: [RFC 1/1] kernel-doc: Support arrays of pointers struct fields

[Randy Dunlap]

Hi Sakari,

On 1/27/24 10:53, Sakari Ailus wrote:
> In a rather unusual arrangement in include/media/v4l2-vp9.h struct
> v4l2_vp9_frame_symbol_counts has fields that are arrays of pointers, not a
> pointer to an array, which is what's usually done.
> 

Yet another kernel-doc bug. I have a list of 5 or 6 or 8 bugs that are
similar to this one, but I didn't have this one.


> Add support for such arrays of pointers to kernel-doc.
> 
> Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>


Did this work for you?
I still see the same warnings as before this patch is applied.


> ---
> Hi Ricardo,
> 
> I tried to ram it together with processing the rest but it seemed
> to complicate processing the usual fields.
> 
>  scripts/kernel-doc | 9 +++++++++
>  1 file changed, 9 insertions(+)
> 
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index e8aefd258a29..728b1ffc0478 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -1509,6 +1509,15 @@ sub create_parameterlist($$$$) {
>  	    $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
>  	    save_struct_actual($param);
>  	    push_parameter($param, $type, $arg, $file, $declaration_name);
> +	} elsif ($arg =~ m/\(.+\)\s*\[/) {
> +	    # array-of-pointers
> +	    $arg =~ tr/#/,/;
> +	    $arg =~ m/[^\(]+\(\s*\*\s*([\w\[\]\.]*?)\s*(\s*\[\s*[\w]+\s*\]\s*)*\)/;
> +	    $param = $1;
> +	    $type = $arg;
> +	    $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
> +	    save_struct_actual($param);
> +	    push_parameter($param, $type, $arg, $file, $declaration_name);
>  	} elsif ($arg) {
>  	    $arg =~ s/\s*:\s*/:/g;
>  	    $arg =~ s/\s*\[/\[/g;


Thanks.
-- 
#Randy

Re: [RFC 1/1] kernel-doc: Support arrays of pointers struct fields

[Sakari Ailus]

Hi Randy,

On Sat, Jan 27, 2024 at 01:01:01PM -0800, Randy Dunlap wrote:
> Hi Sakari,
> 
> On 1/27/24 10:53, Sakari Ailus wrote:
> > In a rather unusual arrangement in include/media/v4l2-vp9.h struct
> > v4l2_vp9_frame_symbol_counts has fields that are arrays of pointers, not a
> > pointer to an array, which is what's usually done.
> > 
> 
> Yet another kernel-doc bug. I have a list of 5 or 6 or 8 bugs that are
> similar to this one, but I didn't have this one.

:-)

Regular expressions are not best for parsing C. It seems to be doable in
practice but imperfect at the same time.

> 
> 
> > Add support for such arrays of pointers to kernel-doc.
> > 
> > Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
> 
> 
> Did this work for you?
> I still see the same warnings as before this patch is applied.

Hmm. How did you test this? I did:

	$ scripts/kernel-doc include/media/v4l2-vp9.h > /dev/null

Without this patch I do get a bunch of errors, with this patch there's no
output. The produced kernel-doc seemed to be fine, too (with the
redirection removed).

> 
> 
> > ---
> > Hi Ricardo,
> > 
> > I tried to ram it together with processing the rest but it seemed
> > to complicate processing the usual fields.
> > 
> >  scripts/kernel-doc | 9 +++++++++
> >  1 file changed, 9 insertions(+)
> > 
> > diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> > index e8aefd258a29..728b1ffc0478 100755
> > --- a/scripts/kernel-doc
> > +++ b/scripts/kernel-doc
> > @@ -1509,6 +1509,15 @@ sub create_parameterlist($$$$) {
> >  	    $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
> >  	    save_struct_actual($param);
> >  	    push_parameter($param, $type, $arg, $file, $declaration_name);
> > +	} elsif ($arg =~ m/\(.+\)\s*\[/) {
> > +	    # array-of-pointers
> > +	    $arg =~ tr/#/,/;
> > +	    $arg =~ m/[^\(]+\(\s*\*\s*([\w\[\]\.]*?)\s*(\s*\[\s*[\w]+\s*\]\s*)*\)/;
> > +	    $param = $1;
> > +	    $type = $arg;
> > +	    $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
> > +	    save_struct_actual($param);
> > +	    push_parameter($param, $type, $arg, $file, $declaration_name);
> >  	} elsif ($arg) {
> >  	    $arg =~ s/\s*:\s*/:/g;
> >  	    $arg =~ s/\s*\[/\[/g;
> 
> 
> Thanks.

-- 
Regards,

Sakari Ailus

Re: [RFC 1/1] kernel-doc: Support arrays of pointers struct fields

[Randy Dunlap]

On 1/27/24 14:41, Sakari Ailus wrote:
> Hi Randy,
> 
> On Sat, Jan 27, 2024 at 01:01:01PM -0800, Randy Dunlap wrote:
>> Hi Sakari,
>>
>> On 1/27/24 10:53, Sakari Ailus wrote:
>>> In a rather unusual arrangement in include/media/v4l2-vp9.h struct
>>> v4l2_vp9_frame_symbol_counts has fields that are arrays of pointers, not a
>>> pointer to an array, which is what's usually done.
>>>
>>
>> Yet another kernel-doc bug. I have a list of 5 or 6 or 8 bugs that are
>> similar to this one, but I didn't have this one.
> 
> :-)
> 
> Regular expressions are not best for parsing C. It seems to be doable in
> practice but imperfect at the same time.
> 
>>
>>
>>> Add support for such arrays of pointers to kernel-doc.
>>>
>>> Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
>>
>>
>> Did this work for you?
>> I still see the same warnings as before this patch is applied.
> 
> Hmm. How did you test this? I did:
> 
> 	$ scripts/kernel-doc include/media/v4l2-vp9.h > /dev/null
> 
> Without this patch I do get a bunch of errors, with this patch there's no
> output. The produced kernel-doc seemed to be fine, too (with the
> redirection removed).
> 

I apologize. I wasn't being careful, just rushing too much.
It works well. Thanks.

Acked-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

>>
>>
>>> ---
>>> Hi Ricardo,
>>>
>>> I tried to ram it together with processing the rest but it seemed
>>> to complicate processing the usual fields.
>>>
>>>  scripts/kernel-doc | 9 +++++++++
>>>  1 file changed, 9 insertions(+)
>>>
>>> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
>>> index e8aefd258a29..728b1ffc0478 100755
>>> --- a/scripts/kernel-doc
>>> +++ b/scripts/kernel-doc
>>> @@ -1509,6 +1509,15 @@ sub create_parameterlist($$$$) {
>>>  	    $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
>>>  	    save_struct_actual($param);
>>>  	    push_parameter($param, $type, $arg, $file, $declaration_name);
>>> +	} elsif ($arg =~ m/\(.+\)\s*\[/) {
>>> +	    # array-of-pointers
>>> +	    $arg =~ tr/#/,/;
>>> +	    $arg =~ m/[^\(]+\(\s*\*\s*([\w\[\]\.]*?)\s*(\s*\[\s*[\w]+\s*\]\s*)*\)/;
>>> +	    $param = $1;
>>> +	    $type = $arg;
>>> +	    $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
>>> +	    save_struct_actual($param);
>>> +	    push_parameter($param, $type, $arg, $file, $declaration_name);
>>>  	} elsif ($arg) {
>>>  	    $arg =~ s/\s*:\s*/:/g;
>>>  	    $arg =~ s/\s*\[/\[/g;
>>
>>
>> Thanks.
> 

-- 
#Randy

Re: [RFC 1/1] kernel-doc: Support arrays of pointers struct fields

[Ricardo Ribalda]

Hi Sakari

Thanks a lot for the patch :)
On Sat, 27 Jan 2024 at 19:53, Sakari Ailus <sakari.ailus@linux.intel.com> wrote:
>
> In a rather unusual arrangement in include/media/v4l2-vp9.h struct
> v4l2_vp9_frame_symbol_counts has fields that are arrays of pointers, not a
> pointer to an array, which is what's usually done.
>
> Add support for such arrays of pointers to kernel-doc.
>
> Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
Tested-by: Ricardo Ribalda <ribalda@chromium.org>
> ---
> Hi Ricardo,
>
> I tried to ram it together with processing the rest but it seemed
> to complicate processing the usual fields.
>
>  scripts/kernel-doc | 9 +++++++++
>  1 file changed, 9 insertions(+)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index e8aefd258a29..728b1ffc0478 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -1509,6 +1509,15 @@ sub create_parameterlist($$$$) {
>             $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
>             save_struct_actual($param);
>             push_parameter($param, $type, $arg, $file, $declaration_name);
> +       } elsif ($arg =~ m/\(.+\)\s*\[/) {
> +           # array-of-pointers
> +           $arg =~ tr/#/,/;
> +           $arg =~ m/[^\(]+\(\s*\*\s*([\w\[\]\.]*?)\s*(\s*\[\s*[\w]+\s*\]\s*)*\)/;
> +           $param = $1;
> +           $type = $arg;
> +           $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
> +           save_struct_actual($param);
> +           push_parameter($param, $type, $arg, $file, $declaration_name);
>         } elsif ($arg) {
>             $arg =~ s/\s*:\s*/:/g;
>             $arg =~ s/\s*\[/\[/g;
> --
> 2.39.2
>


-- 
Ricardo Ribalda

Re: [RFC 1/1] kernel-doc: Support arrays of pointers struct fields

[Jonathan Corbet]

Sakari Ailus <sakari.ailus@linux.intel.com> writes:

> In a rather unusual arrangement in include/media/v4l2-vp9.h struct
> v4l2_vp9_frame_symbol_counts has fields that are arrays of pointers, not a
> pointer to an array, which is what's usually done.
>
> Add support for such arrays of pointers to kernel-doc.
>
> Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
> ---
> Hi Ricardo,
>
> I tried to ram it together with processing the rest but it seemed
> to complicate processing the usual fields.
>
>  scripts/kernel-doc | 9 +++++++++
>  1 file changed, 9 insertions(+)

So I went to apply this...but b4 then pulls in a whole series of
patches, none of which were sent to me.  Since this says "1/1", I was
not expecting that...  I've unapplied it; can I get something that isn't
buried in a bunch of other work?

Thanks,

jon

Re: [RFC 1/1] kernel-doc: Support arrays of pointers struct fields

[Ricardo Ribalda]

Hi Jon,

On Tue, 30 Jan 2024 at 22:10, Jonathan Corbet <corbet@lwn.net> wrote:
>
> Sakari Ailus <sakari.ailus@linux.intel.com> writes:
>
> > In a rather unusual arrangement in include/media/v4l2-vp9.h struct
> > v4l2_vp9_frame_symbol_counts has fields that are arrays of pointers, not a
> > pointer to an array, which is what's usually done.
> >
> > Add support for such arrays of pointers to kernel-doc.
> >
> > Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
> > ---
> > Hi Ricardo,
> >
> > I tried to ram it together with processing the rest but it seemed
> > to complicate processing the usual fields.
> >
> >  scripts/kernel-doc | 9 +++++++++
> >  1 file changed, 9 insertions(+)
>
> So I went to apply this...but b4 then pulls in a whole series of
> patches, none of which were sent to me.  Since this says "1/1", I was
> not expecting that...  I've unapplied it; can I get something that isn't
> buried in a bunch of other work?
>

b4 shazam -P _ 20240127185311.391940-1-sakari.ailus@linux.intel.com

worked with me, including the trailers... Do you prefer to try that or
to wait for Sakari to resend it?

Regards!

> Thanks,
>
> jon



-- 
Ricardo Ribalda

Re: [RFC 1/1] kernel-doc: Support arrays of pointers struct fields

[Jonathan Corbet]

Ricardo Ribalda <ribalda@chromium.org> writes:

> Hi Jon,
>
> On Tue, 30 Jan 2024 at 22:10, Jonathan Corbet <corbet@lwn.net> wrote:
>>
>> Sakari Ailus <sakari.ailus@linux.intel.com> writes:
>>
>> > In a rather unusual arrangement in include/media/v4l2-vp9.h struct
>> > v4l2_vp9_frame_symbol_counts has fields that are arrays of pointers, not a
>> > pointer to an array, which is what's usually done.
>> >
>> > Add support for such arrays of pointers to kernel-doc.
>> >
>> > Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
>> > ---
>> > Hi Ricardo,
>> >
>> > I tried to ram it together with processing the rest but it seemed
>> > to complicate processing the usual fields.
>> >
>> >  scripts/kernel-doc | 9 +++++++++
>> >  1 file changed, 9 insertions(+)
>>
>> So I went to apply this...but b4 then pulls in a whole series of
>> patches, none of which were sent to me.  Since this says "1/1", I was
>> not expecting that...  I've unapplied it; can I get something that isn't
>> buried in a bunch of other work?
>>
>
> b4 shazam -P _ 20240127185311.391940-1-sakari.ailus@linux.intel.com
>
> worked with me, including the trailers... Do you prefer to try that or
> to wait for Sakari to resend it?

Yes, I can work out ways too - going back to the dark pre-b4 days if
nothing else :)  But I'd rather not blindly apply a patch that clearly
seems to be a part of a larger set that I've not seen.  Getting a
standalone version would be preferable.

Thanks,

jon