[RFC] scripts: kernel-doc: fix attribute capture in function parsing

[RFC] scripts: kernel-doc: fix attribute capture in function parsing

[Aditya Srivastava]

Currently, kernel-doc warns for function prototype parsing on the
presence of additional attributes in the definition.

E.g., running kernel-doc -none on include/rdma/iw_cm.h causes this
warning:
"warning: cannot understand function prototype: 'const char *__attribute_const__ iwcm_reject_msg(int reason); '"

Here, the prototype parsing does not take into account the presence
of attribute, "__attribute_const__" before function name.

Provide a simple fix by adding "__attribute_const__" in the corresponding
regex expression.

A quick evaluation by running 'kernel-doc -none' on 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>
---
 scripts/kernel-doc | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 68df17877384..8673dc783309 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1753,6 +1753,7 @@ sub dump_function($$) {
     my $prototype = shift;
     my $file = shift;
     my $noret = 0;
+    my $attribute_const = qr{__attribute_const__};
 
     print_lineno($new_start_line);
 
@@ -1808,7 +1809,7 @@ sub dump_function($$) {
 	$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
 	$prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
 	$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
-	$prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
+	$prototype =~ m/^(\w+\s+\w+\s*\*+$attribute_const?)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
 	$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
 	$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
 	$prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
-- 
2.17.1

Re: [RFC] scripts: kernel-doc: fix attribute capture in function parsing

[Matthew Wilcox]

On Fri, Mar 05, 2021 at 11:50:00PM +0530, Aditya Srivastava wrote:
> Provide a simple fix by adding "__attribute_const__" in the corresponding
> regex expression.
> 
> A quick evaluation by running 'kernel-doc -none' on kernel-tree reveals
> that no additional warning or error has been added or removed by the fix.

I'm no perlmonger, but why isn't this simply:

+++ b/scripts/kernel-doc
@@ -1753,6 +1753,7 @@ sub dump_function($$) {
     $prototype =~ s/^__inline +//;
     $prototype =~ s/^__always_inline +//;
     $prototype =~ s/^noinline +//;
+    $prototype =~ s/__attribute_const__ +//;
     $prototype =~ s/__init +//;
     $prototype =~ s/__init_or_module +//;
     $prototype =~ s/__meminit +//;

(completely untested)

> +++ b/scripts/kernel-doc
> @@ -1753,6 +1753,7 @@ sub dump_function($$) {
>      my $prototype = shift;
>      my $file = shift;
>      my $noret = 0;
> +    my $attribute_const = qr{__attribute_const__};
>  
>      print_lineno($new_start_line);
>  
> @@ -1808,7 +1809,7 @@ sub dump_function($$) {
>  	$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
>  	$prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
>  	$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
> -	$prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
> +	$prototype =~ m/^(\w+\s+\w+\s*\*+$attribute_const?)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
>  	$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
>  	$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
>  	$prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||

Re: [RFC] scripts: kernel-doc: fix attribute capture in function parsing

[Aditya]

On 6/3/21 12:13 am, Matthew Wilcox wrote:
> On Fri, Mar 05, 2021 at 11:50:00PM +0530, Aditya Srivastava wrote:
>> Provide a simple fix by adding "__attribute_const__" in the corresponding
>> regex expression.
>>
>> A quick evaluation by running 'kernel-doc -none' on kernel-tree reveals
>> that no additional warning or error has been added or removed by the fix.
> 
> I'm no perlmonger, but why isn't this simply:
> 
> +++ b/scripts/kernel-doc
> @@ -1753,6 +1753,7 @@ sub dump_function($$) {
>      $prototype =~ s/^__inline +//;
>      $prototype =~ s/^__always_inline +//;
>      $prototype =~ s/^noinline +//;
> +    $prototype =~ s/__attribute_const__ +//;
>      $prototype =~ s/__init +//;
>      $prototype =~ s/__init_or_module +//;
>      $prototype =~ s/__meminit +//;
> 
> (completely untested)
> 
>> +++ b/scripts/kernel-doc
>> @@ -1753,6 +1753,7 @@ sub dump_function($$) {
>>      my $prototype = shift;
>>      my $file = shift;
>>      my $noret = 0;
>> +    my $attribute_const = qr{__attribute_const__};
>>  
>>      print_lineno($new_start_line);
>>  
>> @@ -1808,7 +1809,7 @@ sub dump_function($$) {
>>  	$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
>>  	$prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
>>  	$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
>> -	$prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
>> +	$prototype =~ m/^(\w+\s+\w+\s*\*+$attribute_const?)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
>>  	$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
>>  	$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
>>  	$prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||

Hi Matthew
You are correct, it should be placed there. I was considering it as a
return type instead.
I'll send a modified v2 with the changes.

Thanks
Aditya

Re: [RFC] scripts: kernel-doc: fix attribute capture in function parsing

[Lukas Bulwahn]

On Fri, Mar 5, 2021 at 8:38 PM Aditya <yashsri421@gmail.com> wrote:
>
> On 6/3/21 12:13 am, Matthew Wilcox wrote:
> > On Fri, Mar 05, 2021 at 11:50:00PM +0530, Aditya Srivastava wrote:
> >> Provide a simple fix by adding "__attribute_const__" in the corresponding
> >> regex expression.
> >>
> >> A quick evaluation by running 'kernel-doc -none' on kernel-tree reveals
> >> that no additional warning or error has been added or removed by the fix.
> >
> > I'm no perlmonger, but why isn't this simply:
> >
> > +++ b/scripts/kernel-doc
> > @@ -1753,6 +1753,7 @@ sub dump_function($$) {
> >      $prototype =~ s/^__inline +//;
> >      $prototype =~ s/^__always_inline +//;
> >      $prototype =~ s/^noinline +//;
> > +    $prototype =~ s/__attribute_const__ +//;
> >      $prototype =~ s/__init +//;
> >      $prototype =~ s/__init_or_module +//;
> >      $prototype =~ s/__meminit +//;
> >
> > (completely untested)
> >
> >> +++ b/scripts/kernel-doc
> >> @@ -1753,6 +1753,7 @@ sub dump_function($$) {
> >>      my $prototype = shift;
> >>      my $file = shift;
> >>      my $noret = 0;
> >> +    my $attribute_const = qr{__attribute_const__};
> >>
> >>      print_lineno($new_start_line);
> >>
> >> @@ -1808,7 +1809,7 @@ sub dump_function($$) {
> >>      $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
> >>      $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
> >>      $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
> >> -    $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
> >> +    $prototype =~ m/^(\w+\s+\w+\s*\*+$attribute_const?)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
> >>      $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
> >>      $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
> >>      $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>
> Hi Matthew
> You are correct, it should be placed there. I was considering it as a
> return type instead.
> I'll send a modified v2 with the changes.
>

Aditya, I also ran:

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

cat kernel-doc-output | grep "cannot understand function prototype:" |
sed 's/[^:].*:[0-9]*: \(.*\)$/\1/' | sort

and I found another instance of failed parsing function prototypes in
mm/percpu.c:2671:

struct pcpu_alloc_info * __flatten pcpu_build_alloc_info(size_t
reserved_size, size_t dyn_size, size_t atom_size,
pcpu_fc_cpu_distance_fn_t cpu_distance_fn)

Could you address that one in your patch as well?

Lukas

[RFC v2] scripts: kernel-doc: fix attribute capture in function parsing

[Aditya Srivastava]

Currently, kernel-doc warns for function prototype parsing on the
presence of attributes "__attribute_const__" and "__flatten" in the
definition.

There are 166 occurrences in ~70 files in the kernel tree for
"__attribute_const__" and 5 occurrences in 4 files for "__flatten".

Out of 166, there are 3 occurrences in three different files with
"__attribute_const__" and a preceding kernel-doc; and, 1 occurrence in
./mm/percpu.c for "__flatten" with a preceding kernel-doc. All other
occurrences have no preceding kernel-doc.

Add support for  "__attribute_const__" and "__flatten" attributes.

A quick evaluation by running 'kernel-doc -none' on 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>
---
Changes in v2:
- Remove "__attribute_const__" from the $return_type capture regex and add to the substituting ones.
- Add support for "__flatten" attribute
- Modify commit message

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

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 68df17877384..e1e562b2e2e7 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1766,12 +1766,14 @@ sub dump_function($$) {
     $prototype =~ s/^noinline +//;
     $prototype =~ s/__init +//;
     $prototype =~ s/__init_or_module +//;
+    $prototype =~ s/__flatten +//;
     $prototype =~ s/__meminit +//;
     $prototype =~ s/__must_check +//;
     $prototype =~ s/__weak +//;
     $prototype =~ s/__sched +//;
     $prototype =~ s/__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +//;
     my $define = $prototype =~ s/^#\s*define\s+//; #ak added
+    $prototype =~ s/__attribute_const__ +//;
     $prototype =~ s/__attribute__\s*\(\(
             (?:
                  [\w\s]++          # attribute name
-- 
2.17.1

Re: [RFC v2] scripts: kernel-doc: fix attribute capture in function parsing

[Jonathan Corbet]

Aditya Srivastava <yashsri421@gmail.com> writes:

> Currently, kernel-doc warns for function prototype parsing on the
> presence of attributes "__attribute_const__" and "__flatten" in the
> definition.
>
> There are 166 occurrences in ~70 files in the kernel tree for
> "__attribute_const__" and 5 occurrences in 4 files for "__flatten".
>
> Out of 166, there are 3 occurrences in three different files with
> "__attribute_const__" and a preceding kernel-doc; and, 1 occurrence in
> ./mm/percpu.c for "__flatten" with a preceding kernel-doc. All other
> occurrences have no preceding kernel-doc.
>
> Add support for  "__attribute_const__" and "__flatten" attributes.
>
> A quick evaluation by running 'kernel-doc -none' on 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>
> ---
> Changes in v2:
> - Remove "__attribute_const__" from the $return_type capture regex and add to the substituting ones.
> - Add support for "__flatten" attribute
> - Modify commit message
>
>  scripts/kernel-doc | 2 ++
>  1 file changed, 2 insertions(+)

Applied, thanks.

jon