[PATCH v4 0/2] kernel-doc: fix typedef function parser

[PATCH v4 0/2] kernel-doc: fix typedef function parser

[Mauro Carvalho Chehab]

Hi Jon,

This small series contain the latest version of the typedef parsing
fixes that we've been discussing as:

	[PATCH v3 01/56] scripts: kernel-doc: fix typedef parsing

As I said there, at least while discussing it, I opted to split the
patch in two.

The first one changes the regex;
The second one is just a cleanup that splits the 3 arguments into 3
vars.

From my side, I'm not 100% confident if the second patch is
worth or not. 

The advantage of it is that it makes easier to read the regex. 
It also also makes clearer about the differences between
the two typedef regex'es that are used there. 

On the other hand, using a site like regex101.com to
test it is harder, as one needs to copy-and-paste 3 expressions
instead of just one.

So, when appliying, feel free to decide to either:

	-  merge both as-is (two separate patches);
	-  fold them into a single patch;
	- drop the second patch.

Mauro Carvalho Chehab (2):
  scripts: kernel-doc: fix typedef parsing
  scripts: kernel-doc: split typedef complex regex

 scripts/kernel-doc | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

-- 
2.26.2

[PATCH v4 1/2] scripts: kernel-doc: fix typedef parsing

[Mauro Carvalho Chehab]

The include/linux/genalloc.h file defined this typedef:

	typedef unsigned long (*genpool_algo_t)(unsigned long *map,unsigned long size,unsigned long start,unsigned int nr,void *data, struct gen_pool *pool, unsigned long start_addr);

Because it has a type composite of two words (unsigned long),
the parser gets the typedef name wrong:

.. c:macro:: long

   **Typedef**: Allocation callback function type definition

Fix the regex in order to accept composite types when
defining a typedef for a function pointer.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/kernel-doc | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 99cd8418ff8a..698835909ac1 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1438,13 +1438,14 @@ sub dump_typedef($$) {
     $x =~ s@/\*.*?\*/@@gos;	# strip comments.
 
     # Parse function prototypes
-    if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
-	$x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
+    if ($x =~ /typedef((?:\s+[\w\*]+){1,8})\s*\(\*?\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
+	$x =~ /typedef((?:\s+[\w\*]+\s+){1,8})\s*\*?(\w\S+)\s*\s*\((.*)\);/) {
 
 	# Function typedefs
 	$return_type = $1;
 	$declaration_name = $2;
 	my $args = $3;
+	$return_type =~ s/^\s+//;
 
 	create_parameterlist($args, ',', $file, $declaration_name);
 
-- 
2.26.2

[PATCH v4 2/2] scripts: kernel-doc: split typedef complex regex

[Mauro Carvalho Chehab]

The typedef regex for function prototypes are very complex.
Split them into 3 separate regex and then join them using
qr.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/kernel-doc | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 698835909ac1..f699cf05d409 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1431,17 +1431,21 @@ sub dump_enum($$) {
     }
 }
 
+my $typedef_type = qr { ((?:\s+[\w\*]+){1,8})\s* }x;
+my $typedef_ident = qr { \*?\s*(\w\S+)\s* }x;
+my $typedef_args = qr { \s*\((.*)\); }x;
+
+my $typedef1 = qr { typedef$typedef_type\($typedef_ident\)$typedef_args }x;
+my $typedef2 = qr { typedef$typedef_type$typedef_ident$typedef_args }x;
+
 sub dump_typedef($$) {
     my $x = shift;
     my $file = shift;
 
     $x =~ s@/\*.*?\*/@@gos;	# strip comments.
 
-    # Parse function prototypes
-    if ($x =~ /typedef((?:\s+[\w\*]+){1,8})\s*\(\*?\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
-	$x =~ /typedef((?:\s+[\w\*]+\s+){1,8})\s*\*?(\w\S+)\s*\s*\((.*)\);/) {
-
-	# Function typedefs
+    # Parse function typedef prototypes
+    if ($x =~ $typedef1 || $x =~ $typedef2) {
 	$return_type = $1;
 	$declaration_name = $2;
 	my $args = $3;
-- 
2.26.2

Re: [PATCH v4 0/2] kernel-doc: fix typedef function parser

[Jonathan Corbet]

On Tue, 27 Oct 2020 11:20:35 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> This small series contain the latest version of the typedef parsing
> fixes that we've been discussing as:
> 
> 	[PATCH v3 01/56] scripts: kernel-doc: fix typedef parsing
> 
> As I said there, at least while discussing it, I opted to split the
> patch in two.
> 
> The first one changes the regex;
> The second one is just a cleanup that splits the 3 arguments into 3
> vars.
> 
> From my side, I'm not 100% confident if the second patch is
> worth or not. 
> 
> The advantage of it is that it makes easier to read the regex. 
> It also also makes clearer about the differences between
> the two typedef regex'es that are used there. 
> 
> On the other hand, using a site like regex101.com to
> test it is harder, as one needs to copy-and-paste 3 expressions
> instead of just one.
> 
> So, when appliying, feel free to decide to either:
> 
> 	-  merge both as-is (two separate patches);
> 	-  fold them into a single patch;
> 	- drop the second patch.

I've gone ahead and applied them both.  Anything that makes the kernel-doc
script more understandable and maintainable is a step in the right
direction, I think.

Thanks,

jon