Skip to contentSkip to conversation

kernel-doc: handle spaces in array size

PATCH Superseded Randy Dunlap 3 participants 8 messages Apr 6, 2007 – Apr 7, 2007

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 kernel-doc: handle spaces in array size

From: Randy Dunlap <[email protected]>

Unfortunately, kernel-doc has problems with a struct field like this:

	uint8_t databuf[NAND_MAX_PAGESIZE + NAND_MAX_OOBSIZE];

simply due to the spaces around the "+" sign, so drop all spaces inside [...] so that parsing is done correctly (in some sense).

Warning(linux-2.6.20-git15/include/linux/mtd/nand.h:304): No description found for parameter 'NAND_MAX_OOBSIZE]'

This needs to sit in -mm for awhile to see if it has any adverse effects.

And yes, this is just a hack until kernel-doc learns to do better parsing.

---
 scripts/kernel-doc |    6 ++++++
 1 file changed, 6 insertions(+)
scripts/kernel-doc +6 -0
@@ -1452,6 +1452,12 @@ sub create_parameterlist($$$) {
 	    $arg =~ s/\s*:\s*/:/g;
 	    $arg =~ s/\s*\[/\[/g;
 
+	    # no spaces inside [array size expression];
+	    # messes up split/pop/shift/unshift below;
+	    while ($arg =~ m/\[.*\s.*\]/) {
+		$arg =~ s/\[(.*)\s(.*)\]/\[$1$2\]/;
+	    }
+
 	    my @args = split('\s*,\s*', $arg);
 	    if ($args[0] =~ m/\*/) {
 		$args[0] =~ s/(\*+)\s*/ $1/;
#1 lore raw
Quoted 10 lines · Randy Dunlap

Unfortunately, kernel-doc has problems with a struct field like this:

	uint8_t databuf[NAND_MAX_PAGESIZE + NAND_MAX_OOBSIZE];

simply due to the spaces around the "+" sign, so drop all spaces inside [...] so that parsing is done correctly (in some sense).

scripts/kernel-doc +0 -0
@@ -1452,6 +1452,12 @@ sub create_parameterlist($$$) {
 	    $arg =~ s/\s*:\s*/:/g;
 	    $arg =~ s/\s*\[/\[/g;

scripts/kernel-doc sub create_parameterlist($$$) { · line 1463

Quoted 10 lines
scripts/kernel-doc +6 -0
 
+	    # no spaces inside [array size expression];
+	    # messes up split/pop/shift/unshift below;
+	    while ($arg =~ m/\[.*\s.*\]/) {
+		$arg =~ s/\[(.*)\s(.*)\]/\[$1$2\]/;
+	    }
+
 	    my @args = split('\s*,\s*', $arg);
 	    if ($args[0] =~ m/\*/) {
 		$args[0] =~ s/(\*+)\s*/ $1/;
	while($arg =~ s/\[(.*)\s+(.*)\]/[$1$2]/) {
	}

should do it, and saves us the pre-matching. (Also note the + at \s) (No need to escape [ and ] in the target pattern.)

I can also offer this gem which should do it the most saving way by matching the inside of [] exactly once, and otherwise matching/replacing only on \s:

	$arg =~ s{\[(.*)\]}{($_=$1)=~s/\s+//g;"[$_]"}e;

(I already hear everyone screaming... ;-)

Jan

#2 lore raw
Quoted 8 lines · On Fri, 6 Apr 2007 21:24:48 +0200 (MEST) Jan Engelhardt wrote:
Quoted 7 lines · Randy Dunlap

Unfortunately, kernel-doc has problems with a struct field like this:

	uint8_t databuf[NAND_MAX_PAGESIZE + NAND_MAX_OOBSIZE];

simply due to the spaces around the "+" sign, so drop all spaces inside [...] so that parsing is done correctly (in some sense).

...

Quoted 6 lines
	while($arg =~ s/\[(.*)\s+(.*)\]/[$1$2]/) {
	}

should do it, and saves us the pre-matching. (Also note the + at \s) (No need to escape [ and ] in the target pattern.)

Yep, that works. Want to send it with sign-off or shall I just send a new patch to akpm?

Quoted 7 lines

I can also offer this gem which should do it the most saving way by matching the inside of [] exactly once, and otherwise matching/replacing only on \s:

	$arg =~ s{\[(.*)\]}{($_=$1)=~s/\s+//g;"[$_]"}e;

(I already hear everyone screaming... ;-)

No, thanks.

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

#3 lore raw
Quoted 14 lines · Randy Dunlap
Quoted 8 lines · On Fri, 6 Apr 2007 21:24:48 +0200 (MEST) Jan Engelhardt wrote:
Quoted 7 lines · Randy Dunlap

Unfortunately, kernel-doc has problems with a struct field like this:

	uint8_t databuf[NAND_MAX_PAGESIZE + NAND_MAX_OOBSIZE];

simply due to the spaces around the "+" sign, so drop all spaces inside [...] so that parsing is done correctly (in some sense).

...

Quoted 1 line
Quoted 8 lines
Quoted 5 lines
	while($arg =~ s/\[(.*)\s+(.*)\]/[$1$2]/) {
	}

should do it, and saves us the pre-matching. (Also note the + at \s) (No need to escape [ and ] in the target pattern.)

Yep, that works. Want to send it with sign-off or shall I just send a new patch to akpm?

Jan

#4 lore raw

PATCH v2 1/1 kernel-doc: handle spaces in array size

From: Jan Engelhardt <[email protected]>

Unfortunately, kernel-doc has problems with a struct field like this:

	uint8_t databuf[NAND_MAX_PAGESIZE + NAND_MAX_OOBSIZE];

simply due to the spaces around the "+" sign, so drop all spaces inside [...] so that parsing is done correctly (in some sense).

Warning(linux-2.6.20-git15/include/linux/mtd/nand.h:304): No description found for parameter 'NAND_MAX_OOBSIZE]'

This needs to sit in -mm for awhile to see if it has any adverse effects.

And yes, this is just a hack until kernel-doc learns to do better parsing.

---
 scripts/kernel-doc |    5 +++++
 1 file changed, 5 insertions(+)
scripts/kernel-doc +5 -0
@@ -1452,6 +1452,11 @@ sub create_parameterlist($$$) {
 	    $arg =~ s/\s*:\s*/:/g;
 	    $arg =~ s/\s*\[/\[/g;
 
+	    # no spaces inside [array size expression];
+	    # messes up split/pop/shift/unshift below;
+	    while ($arg =~ s/\[(.*)\s+(.*)\]/[$1$2]/) {
+	    }
+
 	    my @args = split('\s*,\s*', $arg);
 	    if ($args[0] =~ m/\*/) {
 		$args[0] =~ s/(\*+)\s*/ $1/;
#5 lore raw

PATCH 1/1 kernel-doc: handle arrays with arithmetic expressions as initializers <was Re: [PATCH v2] kernel-doc: handle spaces in array size>

Quoted 26 lines · Randy Dunlap

From: Jan Engelhardt <[email protected]>

Unfortunately, kernel-doc has problems with a struct field like this:

	uint8_t databuf[NAND_MAX_PAGESIZE + NAND_MAX_OOBSIZE];

simply due to the spaces around the "+" sign, so drop all spaces inside [...] so that parsing is done correctly (in some sense).

Warning(linux-2.6.20-git15/include/linux/mtd/nand.h:304): No description found for parameter 'NAND_MAX_OOBSIZE]'

This needs to sit in -mm for awhile to see if it has any adverse effects.

And yes, this is just a hack until kernel-doc learns to do better parsing.

---
 scripts/kernel-doc |    5 +++++
 1 file changed, 5 insertions(+)
scripts/kernel-doc +0 -0
@@ -1452,6 +1452,11 @@ sub create_parameterlist($$$) {
 	    $arg =~ s/\s*:\s*/:/g;
 	    $arg =~ s/\s*\[/\[/g;

scripts/kernel-doc sub create_parameterlist($$$) {

Quoted 10 lines
scripts/kernel-doc +5 -1
 
+	    # no spaces inside [array size expression];
+	    # messes up split/pop/shift/unshift below;
+	    while ($arg =~ s/\[(.*)\s+(.*)\]/[$1$2]/) {
+	    }
+
 	    my @args = split('\s*,\s*', $arg);
 	    if ($args[0] =~ m/\*/) {
 		$args[0] =~ s/(\*+)\s*/ $1/;
-

In a different approach here's a patch that handles the special case of composite arithmetic expressions in array size initializers. With it, prior to pushing the split strings on the @first_arg array, I split the keywords before the array name as before and then keep the array name along with the subscript expression as a single whole element which gets pushed last. In this manner, kernel-doc produces correct output without removing whitespaces which makes the array subscripts unreadable in the docs.

scripts/kernel-doc renamed from scripts/kernel-doc.orig +10 -1
@@ -1456,7 +1456,16 @@ sub create_parameterlist($$$) {
 	    if ($args[0] =~ m/\*/) {
 		$args[0] =~ s/(\*+)\s*/ $1/;
 	    }
-	    my @first_arg = split('\s+', shift @args);
+
+	    my @first_arg;
+	    if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
+		    shift @args;
+		    push(@first_arg, split('\s+', $1));
+		    push(@first_arg, $2);
+	    } else {
+		    @first_arg = split('\s+', shift @args);
+	    }
+
 	    unshift(@args, pop @first_arg);
 	    $type = join " ", @first_arg;
 
Signature · 2 lines
Regards/Gruß,
    Boris.
#6 lore raw

Re: [PATCH] kernel-doc: handle arrays with arithmetic expressions as initializers <was Re: [PATCH v2] kernel-doc: handle spaces in array size>

Quoted 8 lines · On Sat, 7 Apr 2007 17:04:44 +0200 Borislav Petkov wrote:

In a different approach here's a patch that handles the special case of composite arithmetic expressions in array size initializers. With it, prior to pushing the split strings on the @first_arg array, I split the keywords before the array name as before and then keep the array name along with the subscript expression as a single whole element which gets pushed last. In this manner, kernel-doc produces correct output without removing whitespaces which makes the array subscripts unreadable in the docs.

Nice job.

Andrew, please drop kernel-doc-handle-spaces-in-array-size.patch and I'll (re)send this one to you.

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

#7 lore raw

PATCH v3 1/1 kernel-doc: handle arrays with arithmetic expressions as initializers

In reply to Borislav Petkov

From: Borislav Petkov <[email protected]>

In a different approach here's a patch that handles the special case of composite arithmetic expressions in array size initializers. With it, prior to pushing the split strings on the @first_arg array, I split the keywords before the array name as before and then keep the array name along with the subscript expression as a single whole element which gets pushed last. In this manner, kernel-doc produces correct output without removing whitespaces which makes the array subscripts unreadable in the docs.

---
 scripts/kernel-doc |   11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)
scripts/kernel-doc +10 -1
@@ -1456,7 +1456,16 @@ sub create_parameterlist($$$) {
 	    if ($args[0] =~ m/\*/) {
 		$args[0] =~ s/(\*+)\s*/ $1/;
 	    }
-	    my @first_arg = split('\s+', shift @args);
+
+	    my @first_arg;
+	    if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
+		    shift @args;
+		    push(@first_arg, split('\s+', $1));
+		    push(@first_arg, $2);
+	    } else {
+		    @first_arg = split('\s+', shift @args);
+	    }
+
 	    unshift(@args, pop @first_arg);
 	    $type = join " ", @first_arg;