[RFC] scripts: kernel-doc: fix array element capture in pointer-to-func parsing

[RFC] scripts: kernel-doc: fix array element capture in pointer-to-func parsing

[Aditya Srivastava]

Currently, kernel-doc causes an unexpected error when array element (i.e.,
"type (*foo[bar])(args)") is present as pointer parameter in
pointer-to-function parsing.

For e.g., running kernel-doc -none on kernel/gcov/gcc_4_7.c causes this
error:
"Use of uninitialized value $param in regexp compilation at ...", in
combination with:
"warning: Function parameter or member '' not described in 'gcov_info'"

Here, the parameter parsing does not take into account the presence of
array element (i.e. square brackets) in $param.

Provide a simple fix by adding square brackets in the regex, responsible
for capturing $param.

A quick evaluation, by running 'kernel-doc -none' on entire kernel-tree,
reveals that no additional warning or error has been added or removed by
the fix.

Suggested-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
Signed-off-by: Aditya Srivastava <yashsri421@gmail.com>
---
* Applies perfectly over next-20210217

 scripts/kernel-doc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index e046e16e4411..8b5bc7bf4bb8 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1553,7 +1553,7 @@ sub create_parameterlist($$$$) {
 	} elsif ($arg =~ m/\(.+\)\s*\(/) {
 	    # pointer-to-function
 	    $arg =~ tr/#/,/;
-	    $arg =~ m/[^\(]+\(\*?\s*([\w\.]*)\s*\)/;
+	    $arg =~ m/[^\(]+\(\*?\s*([\w\[\]\.]*)\s*\)/;
 	    $param = $1;
 	    $type = $arg;
 	    $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
-- 
2.17.1

Re: [RFC] scripts: kernel-doc: fix array element capture in pointer-to-func parsing

[Lukas Bulwahn]

On Wed, Feb 17, 2021 at 3:56 PM Aditya Srivastava <yashsri421@gmail.com> wrote:
>
> Currently, kernel-doc causes an unexpected error when array element (i.e.,
> "type (*foo[bar])(args)") is present as pointer parameter in
> pointer-to-function parsing.
>
> For e.g., running kernel-doc -none on kernel/gcov/gcc_4_7.c causes this
> error:
> "Use of uninitialized value $param in regexp compilation at ...", in
> combination with:
> "warning: Function parameter or member '' not described in 'gcov_info'"
>
> Here, the parameter parsing does not take into account the presence of
> array element (i.e. square brackets) in $param.
>
> Provide a simple fix by adding square brackets in the regex, responsible
> for capturing $param.
>
> A quick evaluation, by running 'kernel-doc -none' on entire kernel-tree,
> reveals that no additional warning or error has been added or removed by
> the fix.
>
> Suggested-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
> Signed-off-by: Aditya Srivastava <yashsri421@gmail.com>
> ---
> * Applies perfectly over next-20210217
>

Aditya, Jonathan,

I have tested this change with:

git ls-files | xargs ./scripts/kernel-doc -none 2>&1 | tee kernel-doc-output

Applied the patch, and re-ran that command and compared the diff.

First, I observed that ./scripts/kernel-doc is not fully deterministic
on my machine, although I could not really pinpoint it to the exact
reason where that comes in.

Secondly, more importantly, the relevant diff affected by this patch is:

< Use of uninitialized value $param in regexp compilation at
./scripts/kernel-doc line 1559, <IN_FILE> line 308.
< Use of uninitialized value $actual in substitution (s///) at
./scripts/kernel-doc line 1523, <IN_FILE> line 308.
< Use of uninitialized value $actual in substitution (s///) at
./scripts/kernel-doc line 1523, <IN_FILE> line 308.
< Use of uninitialized value $param in substitution (s///) at
./scripts/kernel-doc line 1617, <IN_FILE> line 308.
< Use of uninitialized value $param in hash element at
./scripts/kernel-doc line 1651, <IN_FILE> line 308.
< Use of uninitialized value $param in pattern match (m//) at
./scripts/kernel-doc line 1651, <IN_FILE> line 308.
< Use of uninitialized value $param in hash element at
./scripts/kernel-doc line 1652, <IN_FILE> line 308.
< Use of uninitialized value $param in pattern match (m//) at
./scripts/kernel-doc line 1654, <IN_FILE> line 308.
< Use of uninitialized value $param in concatenation (.) or string at
./scripts/kernel-doc line 1655, <IN_FILE> line 308.
< drivers/net/wireless/broadcom/brcm80211/brcmfmac/fweh.h:308:
warning: Function parameter or member '' not described in
'brcmf_fweh_info'
< Use of uninitialized value $param in hash element at
./scripts/kernel-doc line 1672, <IN_FILE> line 308.


< Use of uninitialized value $param in regexp compilation at
./scripts/kernel-doc line 1559, <IN_FILE> line 96.
< Use of uninitialized value $actual in substitution (s///) at
./scripts/kernel-doc line 1523, <IN_FILE> line 96.
< Use of uninitialized value $actual in substitution (s///) at
./scripts/kernel-doc line 1523, <IN_FILE> line 96.
< Use of uninitialized value $param in substitution (s///) at
./scripts/kernel-doc line 1617, <IN_FILE> line 96.
< Use of uninitialized value $param in hash element at
./scripts/kernel-doc line 1651, <IN_FILE> line 96.
< Use of uninitialized value $param in pattern match (m//) at
./scripts/kernel-doc line 1651, <IN_FILE> line 96.
< Use of uninitialized value $param in hash element at
./scripts/kernel-doc line 1652, <IN_FILE> line 96.
< Use of uninitialized value $param in pattern match (m//) at
./scripts/kernel-doc line 1654, <IN_FILE> line 96.
< Use of uninitialized value $param in concatenation (.) or string at
./scripts/kernel-doc line 1655, <IN_FILE> line 96.
< kernel/gcov/gcc_4_7.c:96: warning: Function parameter or member ''
not described in 'gcov_info'
< Use of uninitialized value $param in hash element at
./scripts/kernel-doc line 1672, <IN_FILE> line 96.

So, I can confirm that the mentioned issue is really resolved with
this patch, and that deserves a tag:

Tested-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>

Thanks, Aditya. When can we expect the next patch for ./scripts/kernel-doc?

Looking forward to running the next test :)

Lukas

Re: [RFC] scripts: kernel-doc: fix array element capture in pointer-to-func parsing

[Jonathan Corbet]

Aditya Srivastava <yashsri421@gmail.com> writes:

> Currently, kernel-doc causes an unexpected error when array element (i.e.,
> "type (*foo[bar])(args)") is present as pointer parameter in
> pointer-to-function parsing.
>
> For e.g., running kernel-doc -none on kernel/gcov/gcc_4_7.c causes this
> error:
> "Use of uninitialized value $param in regexp compilation at ...", in
> combination with:
> "warning: Function parameter or member '' not described in 'gcov_info'"

In the future, please quote error messages from the kernel verbatim.
You can trim irrelevant stuff before or after, but please do not edit
them in this way.  That helps me to understand what you are fixing, and
is also useful for anybody else who might be searching for a solution to
the same problem.

> Here, the parameter parsing does not take into account the presence of
> array element (i.e. square brackets) in $param.
>
> Provide a simple fix by adding square brackets in the regex, responsible
> for capturing $param.
>
> A quick evaluation, by running 'kernel-doc -none' on entire kernel-tree,
> reveals that no additional warning or error has been added or removed by
> the fix.
>
> Suggested-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
> Signed-off-by: Aditya Srivastava <yashsri421@gmail.com>
> ---
> * Applies perfectly over next-20210217
>
>  scripts/kernel-doc | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index e046e16e4411..8b5bc7bf4bb8 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -1553,7 +1553,7 @@ sub create_parameterlist($$$$) {
>  	} elsif ($arg =~ m/\(.+\)\s*\(/) {
>  	    # pointer-to-function
>  	    $arg =~ tr/#/,/;
> -	    $arg =~ m/[^\(]+\(\*?\s*([\w\.]*)\s*\)/;
> +	    $arg =~ m/[^\(]+\(\*?\s*([\w\[\]\.]*)\s*\)/;
>  	    $param = $1;
>  	    $type = $arg;
>  	    $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
> -- 

...meanwhile, I have applied this one, thanks.

jon

Re: [RFC] scripts: kernel-doc: fix array element capture in pointer-to-func parsing

[Aditya]

On 23/2/21 3:03 am, Jonathan Corbet wrote:
> Aditya Srivastava <yashsri421@gmail.com> writes:
> 
>> Currently, kernel-doc causes an unexpected error when array element (i.e.,
>> "type (*foo[bar])(args)") is present as pointer parameter in
>> pointer-to-function parsing.
>>
>> For e.g., running kernel-doc -none on kernel/gcov/gcc_4_7.c causes this
>> error:
>> "Use of uninitialized value $param in regexp compilation at ...", in
>> combination with:
>> "warning: Function parameter or member '' not described in 'gcov_info'"
> 
> In the future, please quote error messages from the kernel verbatim.
> You can trim irrelevant stuff before or after, but please do not edit
> them in this way.  That helps me to understand what you are fixing, and
> is also useful for anybody else who might be searching for a solution to
> the same problem.
> 
>> Here, the parameter parsing does not take into account the presence of
>> array element (i.e. square brackets) in $param.
>>
>> Provide a simple fix by adding square brackets in the regex, responsible
[]
>> -- 
> 
> ...meanwhile, I have applied this one, thanks.
> 

Thanks Jonathan! Will keep this in mind..

Thanks
Aditya