2013-09-04 00:34:31

by Joe Perches

Subject: [PATCH] kernel-doc: Update script to find more "Return:" sections

Many kernel-doc return description sections headers
use variants of the "Return:" section prefix.

(some or maybe even most of these aren't in
kernel-doc sections, but many are)

$ git grep -E -i "^\s*\*\s*return[s]?:"| \
cut -f2- -d":" | awk '{print $1 $2}' | \
sort | uniq -c
121 *return:
838 *Return:
778 *RETURN:
191 *returns:
1965 *Returns:
603 *RETURNS:

Rather than change all of the variants to the
canonical "Return:", adapt the script to accept
case insensitive "Return:" and "Returns:"

Signed-off-by: Joe Perches <[email protected]>
---

I don't know that this actually works.
It does seem right though.

Randy? Rob? Can you test this please?

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

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 4305b2f..2b96411 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -418,6 +418,7 @@ sub dump_section {
$parameterdescs{$name} = $contents;
$sectcheck = $sectcheck . $name . " ";
} else {
+ $name = "Return" if $name =~ /^return[s]?$/i;
# print STDERR "other section '$name' = '$contents'\n";
if (defined($sections{$name}) && ($sections{$name} ne "")) {
print STDERR "Error(${file}:$.): duplicate section name '$name'\n";

2013-09-05 18:20:37

by Randy Dunlap

Subject: Re: [PATCH] kernel-doc: Update script to find more "Return:" sections

On 09/03/13 17:34, Joe Perches wrote:
> Many kernel-doc return description sections headers
> use variants of the "Return:" section prefix.
>
> (some or maybe even most of these aren't in
> kernel-doc sections, but many are)
>
> $ git grep -E -i "^\s*\*\s*return[s]?:"| \
> cut -f2- -d":" | awk '{print $1 $2}' | \
> sort | uniq -c
> 121 *return:
> 838 *Return:
> 778 *RETURN:
> 191 *returns:
> 1965 *Returns:
> 603 *RETURNS:
>
> Rather than change all of the variants to the
> canonical "Return:", adapt the script to accept
> case insensitive "Return:" and "Returns:"
>
> Signed-off-by: Joe Perches <[email protected]>
> ---
>
> I don't know that this actually works.
> It does seem right though.
>
> Randy? Rob? Can you test this please?

Works for me. Thanks.

Tested-by: Randy Dunlap <[email protected]>


>
> scripts/kernel-doc | 1 +
> 1 file changed, 1 insertion(+)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 4305b2f..2b96411 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -418,6 +418,7 @@ sub dump_section {
> $parameterdescs{$name} = $contents;
> $sectcheck = $sectcheck . $name . " ";
> } else {
> + $name = "Return" if $name =~ /^return[s]?$/i;
> # print STDERR "other section '$name' = '$contents'\n";
> if (defined($sections{$name}) && ($sections{$name} ne "")) {
> print STDERR "Error(${file}:$.): duplicate section name '$name'\n";
>
>
> --



--
~Randy

2013-09-09 01:05:55

by Rob Landley

Subject: Re: [PATCH] kernel-doc: Update script to find more "Return:" sections

On 09/03/2013 07:34:28 PM, Joe Perches wrote:
> Many kernel-doc return description sections headers
> use variants of the "Return:" section prefix.
>
> (some or maybe even most of these aren't in
> kernel-doc sections, but many are)
>
> $ git grep -E -i "^\s*\*\s*return[s]?:"| \
> cut -f2- -d":" | awk '{print $1 $2}' | \
> sort | uniq -c
> 121 *return:
> 838 *Return:
> 778 *RETURN:
> 191 *returns:
> 1965 *Returns:
> 603 *RETURNS:
>
> Rather than change all of the variants to the
> canonical "Return:", adapt the script to accept
> case insensitive "Return:" and "Returns:"
>
> Signed-off-by: Joe Perches <[email protected]>
> ---
>
> I don't know that this actually works.
> It does seem right though.
>
> Randy? Rob? Can you test this please?

I stopped reading this file at the line "#!/usr/bin/perl -w", but I'm
not sure if this is the right approach. Something that finds these and
lets us patch them to the cannonical version might be more appropriate.

Or are you going to add similar fuzzy matching for all the other
keywords?

Rob-

2013-09-09 04:11:38

by Joe Perches

Subject: Re: [PATCH] kernel-doc: Update script to find more "Return:" sections

On Sun, 2013-09-08 at 20:05 -0500, Rob Landley wrote:
> On 09/03/2013 07:34:28 PM, Joe Perches wrote:
> > Many kernel-doc return description sections headers
> > use variants of the "Return:" section prefix.
> >
> > (some or maybe even most of these aren't in
> > kernel-doc sections, but many are)
> >
> > $ git grep -E -i "^\s*\*\s*return[s]?:"| \
> > cut -f2- -d":" | awk '{print $1 $2}' | \
> > sort | uniq -c
> > 121 *return:
> > 838 *Return:
> > 778 *RETURN:
> > 191 *returns:
> > 1965 *Returns:
> > 603 *RETURNS:
> >
> > Rather than change all of the variants to the
> > canonical "Return:", adapt the script to accept
> > case insensitive "Return:" and "Returns:"
> >
> > Signed-off-by: Joe Perches <[email protected]>
> > ---
> >
> > I don't know that this actually works.
> > It does seem right though.
> >
> > Randy? Rob? Can you test this please?
>
> I stopped reading this file at the line "#!/usr/bin/perl -w", but I'm
> not sure if this is the right approach. Something that finds these and
> lets us patch them to the cannonical version might be more appropriate.

~3500 different lines to patch is a lot.

> Or are you going to add similar fuzzy matching for all the other
> keywords?

What other keywords are there that are not freeform?

The only other style I know of is @arg: