docs: kdoc: improvements to dump_function() and thereabouts

[PATCH 13/13] docs: kdoc: a few more dump_typedef() tweaks

Posted by Jonathan Corbet 5 months ago

Merge "typedef" into the typedef_type pattern rather than repeating it
later, and add some comments.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 scripts/lib/kdoc/kdoc_parser.py | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
index ad9df0536bbf..8215948dd548 100644
--- a/scripts/lib/kdoc/kdoc_parser.py
+++ b/scripts/lib/kdoc/kdoc_parser.py
@@ -1026,13 +1026,15 @@ class KernelDoc:
         """
         Stores a typedef inside self.entries array.
         """
-
-        typedef_type = r'((?:\s+[\w*]+\b){0,7}\s+(?:\w+\b|\*+))\s*'
+        #
+        # We start by looking for function typedefs.
+        #
+        typedef_type = r'typedef((?:\s+[\w*]+\b){0,7}\s+(?:\w+\b|\*+))\s*'
         typedef_ident = r'\*?\s*(\w\S+)\s*'
         typedef_args = r'\s*\((.*)\);'
 
-        typedef1 = KernRe(r'typedef' + typedef_type + r'\(' + typedef_ident + r'\)' + typedef_args)
-        typedef2 = KernRe(r'typedef' + typedef_type + typedef_ident + typedef_args)
+        typedef1 = KernRe(typedef_type + r'\(' + typedef_ident + r'\)' + typedef_args)
+        typedef2 = KernRe(typedef_type + typedef_ident + typedef_args)
 
         # Parse function typedef prototypes
         for r in [typedef1, typedef2]:
@@ -1048,16 +1050,16 @@ class KernelDoc:
                               f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead\n")
                 return
 
-            decl_type = 'function'
-            self.create_parameter_list(ln, decl_type, args, ',', declaration_name)
+            self.create_parameter_list(ln, 'function',_type, args, ',', declaration_name)
 
-            self.output_declaration(decl_type, declaration_name,
+            self.output_declaration('function', declaration_name,
                                     typedef=True,
                                     functiontype=return_type,
                                     purpose=self.entry.declaration_purpose)
             return
-
-        # Parse simple typedefs
+        #
+        # Not a function, try to parse a simple typedef.
+        #
         r = KernRe(r'typedef.*\s+(\w+)\s*;')
         if r.match(proto):
             declaration_name = r.group(1)
-- 
2.51.0

Re: [PATCH 13/13] docs: kdoc: a few more dump_typedef() tweaks

Posted by Akira Yokosawa 5 months ago

Hi Jon,

A quick report on minor regression. Please see below.

On Tue,  9 Sep 2025 14:43:49 -0600, Jonathan Corbet wrote:
> Merge "typedef" into the typedef_type pattern rather than repeating it
> later, and add some comments.

I'm seeing new warnings after applying 13/13:

WARNING: kernel-doc './scripts/kernel-doc.py -rst -enable-lineno ./include/media/demux.h' processing failed with: NameError("name '_type' is not defined")
WARNING: kernel-doc './scripts/kernel-doc.py -rst -enable-lineno ./include/media/v4l2-ioctl.h' processing failed with: NameError("name '_type' is not defined")
WARNING: kernel-doc './scripts/kernel-doc.py -rst -enable-lineno ./include/media/v4l2-ctrls.h' processing failed with: NameError("name '_type' is not defined")
WARNING: kernel-doc './scripts/kernel-doc.py -rst -enable-lineno ./include/media/v4l2-dv-timings.h' processing failed with: NameError("name '_type' is not defined")
WARNING: kernel-doc './scripts/kernel-doc.py -rst -enable-lineno ./include/media/videobuf2-core.h' processing failed with: NameError("name '_type' is not defined")
WARNING: kernel-doc './scripts/kernel-doc.py -rst -enable-lineno ./include/linux/hte.h' processing failed with: NameError("name '_type' is not defined")
WARNING: kernel-doc './scripts/kernel-doc.py -rst -enable-lineno ./include/linux/xarray.h' processing failed with: NameError("name '_type' is not defined")
WARNING: kernel-doc './scripts/kernel-doc.py -rst -enable-lineno -function gen_pool_add ./include/linux/genalloc.h' processing failed with: NameError("name '_type' is not defined")
WARNING: kernel-doc './scripts/kernel-doc.py -rst -enable-lineno -function gen_pool_alloc ./include/linux/genalloc.h' processing failed with: NameError("name '_type' is not defined")
WARNING: kernel-doc './scripts/kernel-doc.py -rst -enable-lineno -function vdso_sgx_enter_enclave_t ./arch/x86/include/uapi/asm/sgx.h' processing failed with: NameError("name '_type' is not defined")

Thanks,
Akira

> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
>  scripts/lib/kdoc/kdoc_parser.py | 20 +++++++++++---------
>  1 file changed, 11 insertions(+), 9 deletions(-)
> 
> diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
> index ad9df0536bbf..8215948dd548 100644
> --- a/scripts/lib/kdoc/kdoc_parser.py
> +++ b/scripts/lib/kdoc/kdoc_parser.py
> @@ -1026,13 +1026,15 @@ class KernelDoc:
>          """
>          Stores a typedef inside self.entries array.
>          """
> -
> -        typedef_type = r'((?:\s+[\w*]+\b){0,7}\s+(?:\w+\b|\*+))\s*'
> +        #
> +        # We start by looking for function typedefs.
> +        #
> +        typedef_type = r'typedef((?:\s+[\w*]+\b){0,7}\s+(?:\w+\b|\*+))\s*'
>          typedef_ident = r'\*?\s*(\w\S+)\s*'
>          typedef_args = r'\s*\((.*)\);'
>  
> -        typedef1 = KernRe(r'typedef' + typedef_type + r'\(' + typedef_ident + r'\)' + typedef_args)
> -        typedef2 = KernRe(r'typedef' + typedef_type + typedef_ident + typedef_args)
> +        typedef1 = KernRe(typedef_type + r'\(' + typedef_ident + r'\)' + typedef_args)
> +        typedef2 = KernRe(typedef_type + typedef_ident + typedef_args)
>  
>          # Parse function typedef prototypes
>          for r in [typedef1, typedef2]:
> @@ -1048,16 +1050,16 @@ class KernelDoc:
>                                f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead\n")
>                  return
>  
> -            decl_type = 'function'
> -            self.create_parameter_list(ln, decl_type, args, ',', declaration_name)
> +            self.create_parameter_list(ln, 'function',_type, args, ',', declaration_name)
>  
> -            self.output_declaration(decl_type, declaration_name,
> +            self.output_declaration('function', declaration_name,
>                                      typedef=True,
>                                      functiontype=return_type,
>                                      purpose=self.entry.declaration_purpose)
>              return
> -
> -        # Parse simple typedefs
> +        #
> +        # Not a function, try to parse a simple typedef.
> +        #
>          r = KernRe(r'typedef.*\s+(\w+)\s*;')
>          if r.match(proto):
>              declaration_name = r.group(1)

Re: [PATCH 13/13] docs: kdoc: a few more dump_typedef() tweaks

Posted by Jonathan Corbet 5 months ago

Akira Yokosawa <akiyks@gmail.com> writes:

> Hi Jon,
>
> A quick report on minor regression. Please see below.
>
> On Tue,  9 Sep 2025 14:43:49 -0600, Jonathan Corbet wrote:
>> Merge "typedef" into the typedef_type pattern rather than repeating it
>> later, and add some comments.
>
> I'm seeing new warnings after applying 13/13:
>
> WARNING: kernel-doc './scripts/kernel-doc.py -rst -enable-lineno ./include/media/demux.h' processing failed with: NameError("name '_type' is not defined")
> WARNING: kernel-doc './scripts/kernel-doc.py -rst -enable-lineno ./include/media/v4l2-ioctl.h' processing failed with: NameError("name '_type' is not defined")
> WARNING: kernel-doc './scripts/kernel-doc.py -rst -enable-lineno ./include/media/v4l2-ctrls.h' processing failed with: NameError("name '_type' is not defined")
> WARNING: kernel-doc './scripts/kernel-doc.py -rst -enable-lineno ./include/media/v4l2-dv-timings.h' processing failed with: NameError("name '_type' is not defined")
> WARNING: kernel-doc './scripts/kernel-doc.py -rst -enable-lineno ./include/media/videobuf2-core.h' processing failed with: NameError("name '_type' is not defined")
> WARNING: kernel-doc './scripts/kernel-doc.py -rst -enable-lineno ./include/linux/hte.h' processing failed with: NameError("name '_type' is not defined")
> WARNING: kernel-doc './scripts/kernel-doc.py -rst -enable-lineno ./include/linux/xarray.h' processing failed with: NameError("name '_type' is not defined")
> WARNING: kernel-doc './scripts/kernel-doc.py -rst -enable-lineno -function gen_pool_add ./include/linux/genalloc.h' processing failed with: NameError("name '_type' is not defined")
> WARNING: kernel-doc './scripts/kernel-doc.py -rst -enable-lineno -function gen_pool_alloc ./include/linux/genalloc.h' processing failed with: NameError("name '_type' is not defined")
> WARNING: kernel-doc './scripts/kernel-doc.py -rst -enable-lineno -function vdso_sgx_enter_enclave_t ./arch/x86/include/uapi/asm/sgx.h' processing failed with: NameError("name '_type' is not defined")

OK, that is embarrassing, not sure how that got through.  My apologies.

An add-on fix is appended if you have the patience to try it; I'll
update the series before too long in any case.

Thanks for testing!

jon

diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
index 8215948dd548..2376f180b1fa 100644
--- a/scripts/lib/kdoc/kdoc_parser.py
+++ b/scripts/lib/kdoc/kdoc_parser.py
@@ -1050,7 +1050,7 @@ class KernelDoc:
                               f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead\n")
                 return
 
-            self.create_parameter_list(ln, 'function',_type, args, ',', declaration_name)
+            self.create_parameter_list(ln, 'function', args, ',', declaration_name)
 
             self.output_declaration('function', declaration_name,
                                     typedef=True,

Re: [PATCH 13/13] docs: kdoc: a few more dump_typedef() tweaks

Posted by Akira Yokosawa 5 months ago

On Wed, 10 Sep 2025 07:46:16 -0600, Jonathan Corbet wrote:
> Akira Yokosawa <akiyks@gmail.com> writes:
> 
>> Hi Jon,
>>
>> A quick report on minor regression. Please see below.
>>
>> On Tue,  9 Sep 2025 14:43:49 -0600, Jonathan Corbet wrote:
>>> Merge "typedef" into the typedef_type pattern rather than repeating it
>>> later, and add some comments.
>>
>> I'm seeing new warnings after applying 13/13:
>>
>> WARNING: kernel-doc './scripts/kernel-doc.py -rst -enable-lineno ./include/media/demux.h' processing failed with: NameError("name '_type' is not defined")

[...]

> 
> OK, that is embarrassing, not sure how that got through.  My apologies.
> 
> An add-on fix is appended if you have the patience to try it; I'll
> update the series before too long in any case.

Testing the one-liner ... , and yes it silenced the warnings.

I can't do any serious reviews on python code, but can do tests on your
"improvements".

All those noisy warnings current docs-next carries ...

Regards,
Akira

> 
> Thanks for testing!
> 
> jon
> 
> diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
> index 8215948dd548..2376f180b1fa 100644
> --- a/scripts/lib/kdoc/kdoc_parser.py
> +++ b/scripts/lib/kdoc/kdoc_parser.py
> @@ -1050,7 +1050,7 @@ class KernelDoc:
>                                f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead\n")
>                  return
>  
> -            self.create_parameter_list(ln, 'function',_type, args, ',', declaration_name)
> +            self.create_parameter_list(ln, 'function', args, ',', declaration_name)
>  
>              self.output_declaration('function', declaration_name,
>                                      typedef=True,