Add kerneldoc for flush_scheduled_work()

PATCH New Randy Dunlap 4 participants 15 messages Aug 13, 2009 – Aug 24, 2009

Subsystems (2)

Documentation SCSI

lore

Share & tools

lore

Randy Dunlap

author

2009-08-13 12:07 UTC #0 lore raw

From: [email protected]

Quoted 21 lines · Ingo Molnar

Quoted 7 lines · James Bottomley
Quoted 6 lines · Alan Stern
Quoted 3 lines · Ingo Molnar
Quoted 3 lines
And here I was thinking kerneldoc doesn't actually work like that, but perhaps Randy fixed it so the initial description can line-wrap?
Quoted 6 lines
Quoted 2 lines
Yes, that's what I thought too. If kerneldoc has been fixed then the description line certainly should get wrapped.
I really don't think it needs to be fixed: it's a feature not a bug. It requires people writing kernel doc actually to think of one line summaries.
As long as the argument is that it's good to have limitations just because it has good effects as well (which the gist of your argument seems to be), i disagree.

Quoted 6 lines

That's a very basic argument of freedom. Just consider the Gestapo which was also a 'feature' to keep criminals in check. Did you know that there were record low levels of petty criminality both in nazi Germany and during communism (and under just about any totalitarian regime)? Still nobody in their right mind is arguing that just due to that they are the right social model ...

| Although I really like how you Godwin'd kerneldoc comments ;-), we do
| have other features that are features because of their limiting effect
| all over the place, don't we?  The 80-columns code rule e.g. or our
| limited set of allowed indenting characters.

Quoted 4 lines

I think this DocBook limitation needs to be fixed, because there are legitimate cases where a function name got too long (for no fault of its own, but for properties of the name-space it is operating in), and we do not want a nanny state beat it into a single line.

| Agreed, just as in the other rules, one should be able to bend this
| one once in a while without technical consequences, i.e. without
| kerneldoc breaking.

Any of you, please feel free to send patches. Thanks.

~Randy

Johannes Weiner

2009-08-13 14:51 UTC #1 lore raw

Hello Randy,

Quoted 41 lines · Randy Dunlap

From: [email protected]
Quoted 21 lines · Ingo Molnar
Quoted 7 lines · James Bottomley
Quoted 6 lines · Alan Stern
Quoted 3 lines · Ingo Molnar
Quoted 3 lines
And here I was thinking kerneldoc doesn't actually work like that, but perhaps Randy fixed it so the initial description can line-wrap?
Quoted 6 lines
Quoted 2 lines
Yes, that's what I thought too. If kerneldoc has been fixed then the description line certainly should get wrapped.
I really don't think it needs to be fixed: it's a feature not a bug. It requires people writing kernel doc actually to think of one line summaries.
As long as the argument is that it's good to have limitations just because it has good effects as well (which the gist of your argument seems to be), i disagree.
Quoted 6 lines
That's a very basic argument of freedom. Just consider the Gestapo which was also a 'feature' to keep criminals in check. Did you know that there were record low levels of petty criminality both in nazi Germany and during communism (and under just about any totalitarian regime)? Still nobody in their right mind is arguing that just due to that they are the right social model ...
| Although I really like how you Godwin'd kerneldoc comments ;-), we do
| have other features that are features because of their limiting effect
| all over the place, don't we?  The 80-columns code rule e.g. or our
| limited set of allowed indenting characters.
Quoted 4 lines
I think this DocBook limitation needs to be fixed, because there are legitimate cases where a function name got too long (for no fault of its own, but for properties of the name-space it is operating in), and we do not want a nanny state beat it into a single line.

Quoted 6 lines

| Agreed, just as in the other rules, one should be able to bend this
| one once in a while without technical consequences, i.e. without
| kerneldoc breaking.

Any of you, please feel free to send patches. Thanks.

Okay, I came up with a syntax to allow continued lines in short descriptions and parameter descriptons.

I can successfully parse

---
/**
* get_tty_driver - find device of a tty
* ...and everything
* @device: device identifier
* ... to identify the device with
* ... that is to be matched
* @index: returns the index of the tty
* ... for your personal pleasure
*
* This routine returns a tty driver structure, given a device number
* and also passes back the index number.
*
* Locking: caller must hold tty_mutex
*/
---

---
Name:

get_tty_driver - find device of a tty and everything

Synopsis:

struct tty_driver * get_tty_driver (dev_t device,

                                    int * index);

Arguments:

device
device identifier to identify the device with that is to be matched
index
returns the index of the tty for your personal pleasure

Description:

This routine returns a tty driver structure, given a device number and also passes back the index number.
Locking:

caller must hold tty_mutex
---

Unfortunately, perl requires me to ignore my pathetic rest of taste, so it may well be horribly ugly without me noticing ;) Would the following work for you? I will happily incorporate improvements.

Hannes

---

scripts/kernel-doc +17 -0

index b52d340..e427b0a 100755
@@ -279,6 +279,7 @@ my $doc_special = "\@\%\$\&";
 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
 my $doc_end = '\*/';
 my $doc_com = '\s*\*\s*';
+my $doc_cont = $doc_com . '\.\.\.\s*(.+)';
 my $doc_decl = $doc_com . '(\w+)';
 my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
 my $doc_content = $doc_com . '(.*)';

@@ -1995,6 +1996,7 @@ sub process_file($) {
     my $identifier;
     my $func;
     my $descr;
+    my $item;
     my $initial_section_counter = $section_counter;
 
     if (defined($ENV{'SRCTREE'})) {

@@ -2044,7 +2046,9 @@ sub process_file($) {
 		    $descr =~ s/\s*$//;
 		    $descr =~ s/\s+/ /;
 		    $declaration_purpose = xml_escape($descr);
+		    $item = \$declaration_purpose;
 		} else {
+		    $state = 2;
 		    $declaration_purpose = "";
 		}

@@ -2075,6 +2079,15 @@ sub process_file($) {
 		++$warnings;
 		$state = 0;
 	    }
+	} elsif (/$doc_cont/o) {
+	    # continued description
+	    if (defined($item)) {
+		chomp($$item);
+		$$item .= " " . $1;
+	    } else {
+		print STDERR "Warning(${file}:$.): Unexpected continuation\n";
+		++$warnings;
+	    }
 	} elsif ($state == 2) {	# look for head: lines, and include content
 	    if (/$doc_sect/o) {
 		$newsection = $1;

@@ -2098,6 +2111,7 @@ sub process_file($) {
 		    }
 		    $contents .= "\n";
 		}
+		$item = \$contents;
 		$section = $newsection;
 	    } elsif (/$doc_end/) {

@@ -2114,6 +2128,7 @@ sub process_file($) {
 
 		$prototype = "";
 		$state = 3;
+		$item = undef;
 		$brcount = 0;
 #		print STDERR "end of doc comment, looking for prototype\n";
 	    } elsif (/$doc_content/) {

@@ -2127,10 +2142,12 @@ sub process_file($) {
 		} else {
 		    $contents .= $1 . "\n";
 		}
+		$item = undef;
 	    } else {
 		# i dont know - bad line?  ignore.
 		print STDERR "Warning(${file}:$.): bad line: $_";
 		++$warnings;
+		$item = undef;
 	    }
 	} elsif ($state == 3) {	# scanning for function '{' (end of prototype)
 	    if ($decl_type eq 'function') {

James Bottomley

maintainer

2009-08-13 15:04 UTC #2 lore raw

Quoted 9 lines · Johannes Weiner

Okay, I came up with a syntax to allow continued lines in short descriptions and parameter descriptons.
I can successfully parse
---
/**
* get_tty_driver - find device of a tty
* ...and everything

I'm not so keen on the ... syntax ... suggestions below

Quoted 54 lines

* @device: device identifier
* ... to identify the device with
* ... that is to be matched
* @index: returns the index of the tty
* ... for your personal pleasure
*
* This routine returns a tty driver structure, given a device number
* and also passes back the index number.
*
* Locking: caller must hold tty_mutex
*/
---
to
---
Name:
get_tty_driver - find device of a tty and everything
Synopsis:
struct tty_driver * get_tty_driver (dev_t device,
                                    int * index);
Arguments:
device
device identifier to identify the device with that is to be matched
index
returns the index of the tty for your personal pleasure
Description:
This routine returns a tty driver structure, given a device number and also passes back the index number.
Locking:
caller must hold tty_mutex
---
Unfortunately, perl requires me to ignore my pathetic rest of taste, so it may well be horribly ugly without me noticing ;) Would the following work for you? I will happily incorporate improvements.
Hannes
---
scripts/kernel-doc +0 -0
index b52d340..e427b0a 100755

scripts/kernel-doc my $doc_special = "\@\%\$\&"; · line 282

Quoted 4 lines

scripts/kernel-doc +1 -0

@@ -279,6 +279,7 @@ my $doc_special = "\@\%\$\&";
 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
 my $doc_end = '\*/';
 my $doc_com = '\s*\*\s*';
+my $doc_cont = $doc_com . '\.\.\.\s*(.+)';

how about making this

$doc_cont = $doc_com.'\s*([^@].*)';

That way anything that doesn't begin with a variable declaration would be treated as comment continuation. Might need a \s is the brackets to ensure blank lines are OK and not treated as continuations.

James

Randy Dunlap

2009-08-13 16:20 UTC #3 lore raw

Quoted 4 lines · James Bottomley

Quoted 3 lines · Johannes Weiner
Okay, I came up with a syntax to allow continued lines in short descriptions and parameter descriptons.

Quoted 8 lines

Quoted 6 lines
I can successfully parse
---
/**
* get_tty_driver - find device of a tty
* ...and everything
I'm not so keen on the ... syntax ... suggestions below

I like this even less than James does.

Quoted 61 lines

Quoted 54 lines
* @device: device identifier
* ... to identify the device with
* ... that is to be matched
* @index: returns the index of the tty
* ... for your personal pleasure
*
* This routine returns a tty driver structure, given a device number
* and also passes back the index number.
*
* Locking: caller must hold tty_mutex
*/
---
to
---
Name:
get_tty_driver - find device of a tty and everything
Synopsis:
struct tty_driver * get_tty_driver (dev_t device,
                                    int * index);
Arguments:
device
device identifier to identify the device with that is to be matched
index
returns the index of the tty for your personal pleasure
Description:
This routine returns a tty driver structure, given a device number and also passes back the index number.
Locking:
caller must hold tty_mutex
---
Unfortunately, perl requires me to ignore my pathetic rest of taste, so it may well be horribly ugly without me noticing ;) Would the following work for you? I will happily incorporate improvements.
Hannes
---
scripts/kernel-doc +0 -0
index b52d340..e427b0a 100755
scripts/kernel-doc my $doc_special = "\@\%\$\&"; · line 282
Quoted 4 lines
scripts/kernel-doc +1 -0
@@ -279,6 +279,7 @@ my $doc_special = "\@\%\$\&";
 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
 my $doc_end = '\*/';
 my $doc_com = '\s*\*\s*';
+my $doc_cont = $doc_com . '\.\.\.\s*(.+)';
how about making this

Quoted 5 lines

$doc_cont = $doc_com.'\s*([^@].*)';
That way anything that doesn't begin with a variable declaration would be treated as comment continuation. Might need a \s is the brackets to ensure blank lines are OK and not treated as continuations.

The goal should be to accept what is currently in the kernel source tree IMO, and this suggestion looks like it would support that.

~Randy

Johannes Weiner

2009-08-13 18:09 UTC #4 lore raw

Quoted 7 lines · Randy Dunlap

Quoted 6 lines · James Bottomley
Quoted 5 lines · Johannes Weiner
Okay, I came up with a syntax to allow continued lines in short descriptions and parameter descriptons.
I can successfully parse

Quoted 8 lines

Quoted 6 lines
Quoted 4 lines
---
/**
* get_tty_driver - find device of a tty
* ...and everything
I'm not so keen on the ... syntax ... suggestions below
I like this even less than James does.

Fair enough.

Quoted 12 lines

Quoted 12 lines
scripts/kernel-doc my $doc_special = "\@\%\$\&"; · line 282
Quoted 9 lines
scripts/kernel-doc +1 -0
index b52d340..e427b0a 100755
@@ -279,6 +279,7 @@ my $doc_special = "\@\%\$\&";
 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
 my $doc_end = '\*/';
 my $doc_com = '\s*\*\s*';
+my $doc_cont = $doc_com . '\.\.\.\s*(.+)';
how about making this

Quoted 5 lines

Quoted 5 lines
$doc_cont = $doc_com.'\s*([^@].*)';
That way anything that doesn't begin with a variable declaration would be treated as comment continuation. Might need a \s is the brackets to ensure blank lines are OK and not treated as continuations.

The \s comes from $doc_com already. We need the [^\s] as you said to skip empty lines but also the slash for this one:

	* @foo: yada
	*/

Quoted 2 lines

The goal should be to accept what is currently in the kernel source tree IMO, and this suggestion looks like it would support that.

Yeah. I also noticed that multi-line blocks starting with @foo: are already handled, making the indirect referencing unnecessary. The result is a bit simpler and more straight-forward, I think.

Hannes

--
From: Johannes Weiner <[email protected]>
Subject: kernel-doc: allow multi-line declaration purpose descriptions

Allow the short description after symbol name and dash in a kernel-doc comment to span multiple lines, like this:

/**
* unmap_mapping_range - unmap the portion of all mmaps in the
* specified address_space corresponding to the specified
* page range in the underlying file.
* @mapping: the address space containing mmaps to be unmapped.
* ...
*/

The short description ends with a newline, a parameter description or the end of the comment block.

Signed-off-by Johannes Weiner <[email protected]>

---

scripts/kernel-doc +8 -0

index b52d340..2921aab 100755
@@ -281,6 +281,7 @@ my $doc_end = '\*/';
 my $doc_com = '\s*\*\s*';
 my $doc_decl = $doc_com . '(\w+)';
 my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
+my $doc_cont = $doc_com . '([^@/\s].*)';
 my $doc_content = $doc_com . '(.*)';
 my $doc_block = $doc_com . 'DOC:\s*(.*)?';

@@ -1995,6 +1996,7 @@ sub process_file($) {
     my $identifier;
     my $func;
     my $descr;
+    my $in_purpose = 0;
     my $initial_section_counter = $section_counter;
 
     if (defined($ENV{'SRCTREE'})) {

@@ -2044,6 +2046,7 @@ sub process_file($) {
 		    $descr =~ s/\s*$//;
 		    $descr =~ s/\s+/ /;
 		    $declaration_purpose = xml_escape($descr);
+		    $in_purpose = 1;
 		} else {
 		    $declaration_purpose = "";
 		}

@@ -2075,7 +2078,12 @@ sub process_file($) {
 		++$warnings;
 		$state = 0;
 	    }
+	} elsif ($in_purpose == 1 && /$doc_cont/o) {
+	    # continued description
+	    chomp($declaration_purpose);
+	    $declaration_purpose .= " " . $1;
 	} elsif ($state == 2) {	# look for head: lines, and include content
+	    $in_purpose = 0;
 	    if (/$doc_sect/o) {
 		$newsection = $1;
 		$newcontents = $2;

Randy Dunlap

author

2009-08-14 18:24 UTC #5 lore raw

Quoted 101 lines · Johannes Weiner

Quoted 5 lines · Randy Dunlap
Quoted 4 lines · James Bottomley
Quoted 3 lines · Johannes Weiner
Okay, I came up with a syntax to allow continued lines in short descriptions and parameter descriptons.
Quoted 8 lines
Quoted 7 lines
Quoted 6 lines
I can successfully parse
---
/**
* get_tty_driver - find device of a tty
* ...and everything
I'm not so keen on the ... syntax ... suggestions below
I like this even less than James does.
Fair enough.
Quoted 11 lines
Quoted 11 lines
scripts/kernel-doc my $doc_special = "\@\%\$\&"; · line 282
Quoted 9 lines
scripts/kernel-doc +1 -0
index b52d340..e427b0a 100755
@@ -279,6 +279,7 @@ my $doc_special = "\@\%\$\&";
 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
 my $doc_end = '\*/';
 my $doc_com = '\s*\*\s*';
+my $doc_cont = $doc_com . '\.\.\.\s*(.+)';
how about making this
Quoted 5 lines
Quoted 5 lines
$doc_cont = $doc_com.'\s*([^@].*)';
That way anything that doesn't begin with a variable declaration would be treated as comment continuation. Might need a \s is the brackets to ensure blank lines are OK and not treated as continuations.
The \s comes from $doc_com already. We need the [^\s] as you said to skip empty lines but also the slash for this one:
	* @foo: yada
	*/
Quoted 2 lines
The goal should be to accept what is currently in the kernel source tree IMO, and this suggestion looks like it would support that.
Yeah. I also noticed that multi-line blocks starting with @foo: are already handled, making the indirect referencing unnecessary. The result is a bit simpler and more straight-forward, I think.
Hannes
--
From: Johannes Weiner <[email protected]>
Subject: kernel-doc: allow multi-line declaration purpose descriptions
Allow the short description after symbol name and dash in a kernel-doc comment to span multiple lines, like this:
/**
* unmap_mapping_range - unmap the portion of all mmaps in the
* specified address_space corresponding to the specified
* page range in the underlying file.
* @mapping: the address space containing mmaps to be unmapped.
* ...
*/
The short description ends with a newline, a parameter description or the end of the comment block.
Signed-off-by Johannes Weiner <[email protected]>
---
scripts/kernel-doc +3 -0
index b52d340..2921aab 100755
@@ -281,6 +281,7 @@ my $doc_end = '\*/';
 my $doc_com = '\s*\*\s*';
 my $doc_decl = $doc_com . '(\w+)';
 my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
+my $doc_cont = $doc_com . '([^@/\s].*)';
 my $doc_content = $doc_com . '(.*)';
 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
 
@@ -1995,6 +1996,7 @@ sub process_file($) {
     my $identifier;
     my $func;
     my $descr;
+    my $in_purpose = 0;
     my $initial_section_counter = $section_counter;
 
     if (defined($ENV{'SRCTREE'})) {
@@ -2044,6 +2046,7 @@ sub process_file($) {
 		    $descr =~ s/\s*$//;
 		    $descr =~ s/\s+/ /;
 		    $declaration_purpose = xml_escape($descr);
+		    $in_purpose = 1;
 		} else {
 		    $declaration_purpose = "";
 		}
@@ -2075,7 +2078,12 @@ sub process_file($) {
 		++$warnings;
 		$state = 0;

scripts/kernel-doc sub process_file($) { · line 2089

Quoted 10 lines

scripts/kernel-doc +5 -0

 	    }
+	} elsif ($in_purpose == 1 && /$doc_cont/o) {
+	    # continued description
+	    chomp($declaration_purpose);
+	    $declaration_purpose .= " " . $1;
 	} elsif ($state == 2) {	# look for head: lines, and include content
+	    $in_purpose = 0;
 	    if (/$doc_sect/o) {
 		$newsection = $1;
 		$newcontents = $2;

Hi Hannes,

This looks good in theory, but it doesn't survive a "make htmldocs" after the patch is applied.

It could be the ending kernel-doc comment characters:
**/

The problem is in drivers/scsi/scsi_devinfo.c:
/**
* scsi_dev_info_list_delete - called from scsi.c:exit_scsi to remove the scsi_dev_info_list. **/
void scsi_exit_devinfo(void)
{

I'm currently on vacation, but I'll look into it more if you can't do so.

Thanks.

Randy Dunlap

author

2009-08-16 19:13 UTC #6 lore raw

PATCH 1/1 scsi: fix func names in kernel-doc

Quoted 126 lines · Randy Dunlap

Quoted 98 lines · Johannes Weiner
Quoted 5 lines · Randy Dunlap
Quoted 4 lines · James Bottomley
Quoted 3 lines · Johannes Weiner
Okay, I came up with a syntax to allow continued lines in short descriptions and parameter descriptons.
Quoted 8 lines
Quoted 7 lines
Quoted 6 lines
I can successfully parse
---
/**
* get_tty_driver - find device of a tty
* ...and everything
I'm not so keen on the ... syntax ... suggestions below
I like this even less than James does.
Fair enough.
Quoted 11 lines
Quoted 11 lines
scripts/kernel-doc my $doc_special = "\@\%\$\&"; · line 282
Quoted 9 lines
scripts/kernel-doc +1 -0
index b52d340..e427b0a 100755
@@ -279,6 +279,7 @@ my $doc_special = "\@\%\$\&";
 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
 my $doc_end = '\*/';
 my $doc_com = '\s*\*\s*';
+my $doc_cont = $doc_com . '\.\.\.\s*(.+)';
how about making this
Quoted 5 lines
Quoted 5 lines
$doc_cont = $doc_com.'\s*([^@].*)';
That way anything that doesn't begin with a variable declaration would be treated as comment continuation. Might need a \s is the brackets to ensure blank lines are OK and not treated as continuations.
The \s comes from $doc_com already. We need the [^\s] as you said to skip empty lines but also the slash for this one:
	* @foo: yada
	*/
Quoted 2 lines
The goal should be to accept what is currently in the kernel source tree IMO, and this suggestion looks like it would support that.
Yeah. I also noticed that multi-line blocks starting with @foo: are already handled, making the indirect referencing unnecessary. The result is a bit simpler and more straight-forward, I think.
Hannes
--
From: Johannes Weiner <[email protected]>
Subject: kernel-doc: allow multi-line declaration purpose descriptions
Allow the short description after symbol name and dash in a kernel-doc comment to span multiple lines, like this:
/**
* unmap_mapping_range - unmap the portion of all mmaps in the
* specified address_space corresponding to the specified
* page range in the underlying file.
* @mapping: the address space containing mmaps to be unmapped.
* ...
*/
The short description ends with a newline, a parameter description or the end of the comment block.
Signed-off-by Johannes Weiner <[email protected]>
---
scripts/kernel-doc +3 -0
index b52d340..2921aab 100755
@@ -281,6 +281,7 @@ my $doc_end = '\*/';
 my $doc_com = '\s*\*\s*';
 my $doc_decl = $doc_com . '(\w+)';
 my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
+my $doc_cont = $doc_com . '([^@/\s].*)';
 my $doc_content = $doc_com . '(.*)';
 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
 
@@ -1995,6 +1996,7 @@ sub process_file($) {
     my $identifier;
     my $func;
     my $descr;
+    my $in_purpose = 0;
     my $initial_section_counter = $section_counter;
 
     if (defined($ENV{'SRCTREE'})) {
@@ -2044,6 +2046,7 @@ sub process_file($) {
 		    $descr =~ s/\s*$//;
 		    $descr =~ s/\s+/ /;
 		    $declaration_purpose = xml_escape($descr);
+		    $in_purpose = 1;
 		} else {
 		    $declaration_purpose = "";
 		}
@@ -2075,7 +2078,12 @@ sub process_file($) {
 		++$warnings;
 		$state = 0;
scripts/kernel-doc sub process_file($) { · line 2089
Quoted 10 lines
scripts/kernel-doc +5 -0
 	    }
+	} elsif ($in_purpose == 1 && /$doc_cont/o) {
+	    # continued description
+	    chomp($declaration_purpose);
+	    $declaration_purpose .= " " . $1;
 	} elsif ($state == 2) {	# look for head: lines, and include content
+	    $in_purpose = 0;
 	    if (/$doc_sect/o) {
 		$newsection = $1;
 		$newcontents = $2;
Hi Hannes,
This looks good in theory, but it doesn't survive a "make htmldocs" after the patch is applied.
It could be the ending kernel-doc comment characters:
**/
The problem is in drivers/scsi/scsi_devinfo.c:
/**
* scsi_dev_info_list_delete - called from scsi.c:exit_scsi to remove the scsi_dev_info_list. **/
void scsi_exit_devinfo(void)
{

Quoted 2 lines

I'm currently on vacation, but I'll look into it more if you can't do so.

Duh. James, the kernel-doc func name and actual func name don't match. Here's a patch for that and one other mismatched func name.

-----
From: Randy Dunlap <[email protected]>

Fix scsi_devinfo.c kernel-doc function names to match actual function names.

Signed-off-by Randy Dunlap <[email protected]>

---
 drivers/scsi/scsi_devinfo.c |    4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

drivers/scsi/scsi_devinfo.c +2 -2

@@ -454,7 +454,7 @@ int scsi_get_device_flags(struct scsi_de
 
 
 /**
- * get_device_flags_keyed - get device specific flags from the dynamic device list.
+ * scsi_get_device_flags_keyed - get device specific flags from the dynamic device list
  * @sdev:       &scsi_device to get flags for
  * @vendor:	vendor name
  * @model:	model name

@@ -685,7 +685,7 @@ MODULE_PARM_DESC(default_dev_flags,
 		 "scsi default device flag integer value");
 
 /**
- * scsi_dev_info_list_delete - called from scsi.c:exit_scsi to remove the scsi_dev_info_list.
+ * scsi_exit_devinfo - remove /proc/scsi/device_info & the scsi_dev_info_list
  **/
 void scsi_exit_devinfo(void)
 {

Johannes Weiner

2009-08-18 09:05 UTC #7 lore raw

In reply to Randy Dunlap

Hello Randy,

Quoted 59 lines · Randy Dunlap

Quoted 31 lines · Johannes Weiner

scripts/kernel-doc +3 -0

index b52d340..2921aab 100755
@@ -281,6 +281,7 @@ my $doc_end = '\*/';
 my $doc_com = '\s*\*\s*';
 my $doc_decl = $doc_com . '(\w+)';
 my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
+my $doc_cont = $doc_com . '([^@/\s].*)';
 my $doc_content = $doc_com . '(.*)';
 my $doc_block = $doc_com . 'DOC:\s*(.*)?';

@@ -1995,6 +1996,7 @@ sub process_file($) {
     my $identifier;
     my $func;
     my $descr;
+    my $in_purpose = 0;
     my $initial_section_counter = $section_counter;
 
     if (defined($ENV{'SRCTREE'})) {

@@ -2044,6 +2046,7 @@ sub process_file($) {
 		    $descr =~ s/\s*$//;
 		    $descr =~ s/\s+/ /;
 		    $declaration_purpose = xml_escape($descr);
+		    $in_purpose = 1;
 		} else {
 		    $declaration_purpose = "";
 		}

@@ -2075,7 +2078,12 @@ sub process_file($) {
 		++$warnings;
 		$state = 0;

scripts/kernel-doc sub process_file($) { · line 2089

Quoted 10 lines

scripts/kernel-doc +5 -0

 	    }
+	} elsif ($in_purpose == 1 && /$doc_cont/o) {
+	    # continued description
+	    chomp($declaration_purpose);
+	    $declaration_purpose .= " " . $1;
 	} elsif ($state == 2) {	# look for head: lines, and include content
+	    $in_purpose = 0;
 	    if (/$doc_sect/o) {
 		$newsection = $1;
 		$newcontents = $2;

Hi Hannes,

This looks good in theory, but it doesn't survive a "make htmldocs" after the patch is applied.

It could be the ending kernel-doc comment characters:
**/

The problem is in drivers/scsi/scsi_devinfo.c:
/**
* scsi_dev_info_list_delete - called from scsi.c:exit_scsi to remove the scsi_dev_info_list. **/
void scsi_exit_devinfo(void)
{

Quoted 2 lines

I'm currently on vacation, but I'll look into it more if you can't do so.

Yeah, it's the terminating **/ which matches $doc_cont. I will try to send an updated version this evening.

Hannes

Johannes Weiner

2009-08-19 22:24 UTC #8 lore raw

Hello,

Quoted 62 lines · Johannes Weiner

Hello Randy,

Quoted 59 lines · Randy Dunlap

Quoted 31 lines · Johannes Weiner

scripts/kernel-doc +3 -0

index b52d340..2921aab 100755
@@ -281,6 +281,7 @@ my $doc_end = '\*/';
 my $doc_com = '\s*\*\s*';
 my $doc_decl = $doc_com . '(\w+)';
 my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
+my $doc_cont = $doc_com . '([^@/\s].*)';
 my $doc_content = $doc_com . '(.*)';
 my $doc_block = $doc_com . 'DOC:\s*(.*)?';

@@ -1995,6 +1996,7 @@ sub process_file($) {
     my $identifier;
     my $func;
     my $descr;
+    my $in_purpose = 0;
     my $initial_section_counter = $section_counter;
 
     if (defined($ENV{'SRCTREE'})) {

@@ -2044,6 +2046,7 @@ sub process_file($) {
 		    $descr =~ s/\s*$//;
 		    $descr =~ s/\s+/ /;
 		    $declaration_purpose = xml_escape($descr);
+		    $in_purpose = 1;
 		} else {
 		    $declaration_purpose = "";
 		}

@@ -2075,7 +2078,12 @@ sub process_file($) {
 		++$warnings;
 		$state = 0;

scripts/kernel-doc sub process_file($) { · line 2089

Quoted 10 lines

scripts/kernel-doc +5 -0

 	    }
+	} elsif ($in_purpose == 1 && /$doc_cont/o) {
+	    # continued description
+	    chomp($declaration_purpose);
+	    $declaration_purpose .= " " . $1;
 	} elsif ($state == 2) {	# look for head: lines, and include content
+	    $in_purpose = 0;
 	    if (/$doc_sect/o) {
 		$newsection = $1;
 		$newcontents = $2;

Hi Hannes,

This looks good in theory, but it doesn't survive a "make htmldocs" after the patch is applied.

It could be the ending kernel-doc comment characters:
**/

The problem is in drivers/scsi/scsi_devinfo.c:
/**
* scsi_dev_info_list_delete - called from scsi.c:exit_scsi to remove the scsi_dev_info_list. **/
void scsi_exit_devinfo(void)
{

Quoted 5 lines

Quoted 2 lines
I'm currently on vacation, but I'll look into it more if you can't do so.
Yeah, it's the terminating **/ which matches $doc_cont. I will try to send an updated version this evening.

I got completely rid of the extra re. Just parse a non-empty content line following the declaration purpose immediately as continuation.

It survives make htmldocs, the scsi_exit_devinfo() doc looks okay and for stuff that had continuation lines before, it does what's expected
- e.g. for the doc of kernel/sched.c::init_sd_power_savings_stats().

It behaves differently for broken docs (mm/page_alloc.c::calculate_zone_inactive_ratio e.g.), but that shouldn't matter.

I didn't find any other misbehaviour when checking random samples.

---
From: Johannes Weiner <[email protected]>
Subject: kernel-doc: allow multi-line declaration purpose descriptions

Allow the short description after symbol name and dash in a kernel-doc comment to span multiple lines, e.g. like this:

The short description ends with a parameter description, an empty line or the end of the comment block.

Signed-off-by Johannes Weiner <[email protected]>

---
 Documentation/kernel-doc-nano-HOWTO.txt |    4 +++-
 scripts/kernel-doc                      |   19 ++++++++++++++-----
 2 files changed, 17 insertions(+), 6 deletions(-)

Documentation/kernel-doc-nano-HOWTO.txt +3 -1

index 4d04572..348b9e5 100644
@@ -66,7 +66,9 @@ Example kernel-doc function comment:
  * The longer description can have multiple paragraphs.
  */
 
-The first line, with the short description, must be on a single line.
+The short description following the subject can span multiple lines
+and ends with an @argument description, an empty line or the end of
+the comment block.
 
 The @argument descriptions must begin on the very next line following
 this opening short function description line, with no intervening

scripts/kernel-doc +14 -5

index b52d340..6194ef5 100755
@@ -1995,6 +1995,7 @@ sub process_file($) {
     my $identifier;
     my $func;
     my $descr;
+    my $in_purpose = 0;
     my $initial_section_counter = $section_counter;
 
     if (defined($ENV{'SRCTREE'})) {

@@ -2044,6 +2045,7 @@ sub process_file($) {
 		    $descr =~ s/\s*$//;
 		    $descr =~ s/\s+/ /;
 		    $declaration_purpose = xml_escape($descr);
+		    $in_purpose = 1;
 		} else {
 		    $declaration_purpose = "";
 		}

@@ -2090,6 +2092,7 @@ sub process_file($) {
 		}
 
 		$in_doc_sect = 1;
+		$in_purpose = 0;
 		$contents = $newcontents;
 		if ($contents ne "") {
 		    while ((substr($contents, 0, 1) eq " ") ||

@@ -2119,11 +2122,17 @@ sub process_file($) {
 	    } elsif (/$doc_content/) {
 		# miguel-style comment kludge, look for blank lines after
 		# @parameter line to signify start of description
-		if ($1 eq "" &&
-			($section =~ m/^@/ || $section eq $section_context)) {
-		    dump_section($file, $section, xml_escape($contents));
-		    $section = $section_default;
-		    $contents = "";
+		if ($1 eq "") {
+		    if ($section =~ m/^@/ || $section eq $section_context) {
+			dump_section($file, $section, xml_escape($contents));
+			$section = $section_default;
+			$contents = "";
+		    }
+		    $in_purpose = 0;
+		} elsif ($in_purpose == 1) {
+		    # Continued declaration purpose
+		    chomp($declaration_purpose);
+		    $declaration_purpose .= " " . $1;
 		} else {
 		    $contents .= $1 . "\n";
 		}

Randy Dunlap

author

2009-08-19 23:21 UTC #9 lore raw

Quoted 6 lines · Johannes Weiner

Quoted 2 lines
Yeah, it's the terminating **/ which matches $doc_cont. I will try to send an updated version this evening.
I got completely rid of the extra re. Just parse a non-empty content line following the declaration purpose immediately as continuation.

Quoted 7 lines

It survives make htmldocs, the scsi_exit_devinfo() doc looks okay and for stuff that had continuation lines before, it does what's expected
- e.g. for the doc of kernel/sched.c::init_sd_power_savings_stats().
It behaves differently for broken docs (mm/page_alloc.c::calculate_zone_inactive_ratio e.g.), but that shouldn't matter.

Right, no problem on that one (for which I sent Andrew a patch some time ago).

Quoted 1 line

I didn't find any other misbehaviour when checking random samples.

It's very close. I only checked/compared one docbook: mac80211. There is some kind of paragraph end handling difference.

In processing include/net/mac80211.h, struct ieee80211_tx_info, without the patch, it ends with:

This structure is placed in skb->cb for three uses: (1) mac80211 TX control - mac80211 tells the driver what to do (2) driver internal use (if applicable) (3) TX status information - driver tells mac80211 what happened

The TX control's sta pointer is only valid during the ->tx call, it may be NULL.

and with the patch, those 2 paragraphs are run together:

I don't think that this will be difficult to find/fix...

Thanks.

Quoted 90 lines

---
From: Johannes Weiner <[email protected]>
Subject: kernel-doc: allow multi-line declaration purpose descriptions

Allow the short description after symbol name and dash in a kernel-doc comment to span multiple lines, e.g. like this:

The short description ends with a parameter description, an empty line or the end of the comment block.

Signed-off-by Johannes Weiner <[email protected]>

---
 Documentation/kernel-doc-nano-HOWTO.txt |    4 +++-
 scripts/kernel-doc                      |   19 ++++++++++++++-----
 2 files changed, 17 insertions(+), 6 deletions(-)

Documentation/kernel-doc-nano-HOWTO.txt +3 -1

index 4d04572..348b9e5 100644
@@ -66,7 +66,9 @@ Example kernel-doc function comment:
  * The longer description can have multiple paragraphs.
  */
 
-The first line, with the short description, must be on a single line.
+The short description following the subject can span multiple lines
+and ends with an @argument description, an empty line or the end of
+the comment block.
 
 The @argument descriptions must begin on the very next line following
 this opening short function description line, with no intervening

scripts/kernel-doc +14 -5

index b52d340..6194ef5 100755
@@ -1995,6 +1995,7 @@ sub process_file($) {
     my $identifier;
     my $func;
     my $descr;
+    my $in_purpose = 0;
     my $initial_section_counter = $section_counter;
 
     if (defined($ENV{'SRCTREE'})) {

@@ -2044,6 +2045,7 @@ sub process_file($) {
 		    $descr =~ s/\s*$//;
 		    $descr =~ s/\s+/ /;
 		    $declaration_purpose = xml_escape($descr);
+		    $in_purpose = 1;
 		} else {
 		    $declaration_purpose = "";
 		}

@@ -2090,6 +2092,7 @@ sub process_file($) {
 		}
 
 		$in_doc_sect = 1;
+		$in_purpose = 0;
 		$contents = $newcontents;
 		if ($contents ne "") {
 		    while ((substr($contents, 0, 1) eq " ") ||

@@ -2119,11 +2122,17 @@ sub process_file($) {
 	    } elsif (/$doc_content/) {
 		# miguel-style comment kludge, look for blank lines after
 		# @parameter line to signify start of description
-		if ($1 eq "" &&
-			($section =~ m/^@/ || $section eq $section_context)) {
-		    dump_section($file, $section, xml_escape($contents));
-		    $section = $section_default;
-		    $contents = "";
+		if ($1 eq "") {
+		    if ($section =~ m/^@/ || $section eq $section_context) {
+			dump_section($file, $section, xml_escape($contents));
+			$section = $section_default;
+			$contents = "";
+		    }
+		    $in_purpose = 0;
+		} elsif ($in_purpose == 1) {
+		    # Continued declaration purpose
+		    chomp($declaration_purpose);
+		    $declaration_purpose .= " " . $1;
 		} else {
 		    $contents .= $1 . "\n";
 		}

Randy Dunlap

author

2009-08-19 23:28 UTC #10 lore raw

Quoted 31 lines · Randy Dunlap

Quoted 5 lines · Johannes Weiner
Quoted 2 lines
Yeah, it's the terminating **/ which matches $doc_cont. I will try to send an updated version this evening.
I got completely rid of the extra re. Just parse a non-empty content line following the declaration purpose immediately as continuation.
Quoted 7 lines
It survives make htmldocs, the scsi_exit_devinfo() doc looks okay and for stuff that had continuation lines before, it does what's expected
- e.g. for the doc of kernel/sched.c::init_sd_power_savings_stats().
It behaves differently for broken docs (mm/page_alloc.c::calculate_zone_inactive_ratio e.g.), but that shouldn't matter.
Right, no problem on that one (for which I sent Andrew a patch some time ago).
Quoted 1 line
I didn't find any other misbehaviour when checking random samples.
It's very close. I only checked/compared one docbook: mac80211. There is some kind of paragraph end handling difference.
In processing include/net/mac80211.h, struct ieee80211_tx_info, without the patch, it ends with:
This structure is placed in skb->cb for three uses: (1) mac80211 TX control - mac80211 tells the driver what to do (2) driver internal use (if applicable) (3) TX status information - driver tells mac80211 what happened
The TX control's sta pointer is only valid during the ->tx call, it may be NULL.
and with the patch, those 2 paragraphs are run together:

Quoted 7 lines

This structure is placed in skb->cb for three uses: (1) mac80211 TX control - mac80211 tells the driver what to do (2) driver internal use (if applicable) (3) TX status information - driver tells mac80211 what happened The TX control's sta pointer is only valid during the ->tx call, it may be NULL.
I don't think that this will be difficult to find/fix...
Thanks.

Bah. There are lots of kernel-doc problems in mac80211.h. I will be sending a patch for those...

Quoted 23 lines

Quoted 23 lines
---
From: Johannes Weiner <[email protected]>
Subject: kernel-doc: allow multi-line declaration purpose descriptions
Allow the short description after symbol name and dash in a kernel-doc comment to span multiple lines, e.g. like this:
/**
* unmap_mapping_range - unmap the portion of all mmaps in the
* specified address_space corresponding to the specified
* page range in the underlying file.
* @mapping: the address space containing mmaps to be unmapped.
* ...
*/
The short description ends with a parameter description, an empty line or the end of the comment block.
Signed-off-by Johannes Weiner <[email protected]>
---
 Documentation/kernel-doc-nano-HOWTO.txt |    4 +++-
 scripts/kernel-doc                      |   19 ++++++++++++++-----
 2 files changed, 17 insertions(+), 6 deletions(-)

Johannes Weiner

2009-08-24 19:07 UTC #11 lore raw

In reply to Randy Dunlap

Quoted 26 lines · Randy Dunlap

Quoted 6 lines · Johannes Weiner
Quoted 2 lines
Yeah, it's the terminating **/ which matches $doc_cont. I will try to send an updated version this evening.
I got completely rid of the extra re. Just parse a non-empty content line following the declaration purpose immediately as continuation.
Quoted 7 lines
It survives make htmldocs, the scsi_exit_devinfo() doc looks okay and for stuff that had continuation lines before, it does what's expected
- e.g. for the doc of kernel/sched.c::init_sd_power_savings_stats().
It behaves differently for broken docs (mm/page_alloc.c::calculate_zone_inactive_ratio e.g.), but that shouldn't matter.
Right, no problem on that one (for which I sent Andrew a patch some time ago).
Quoted 1 line
I didn't find any other misbehaviour when checking random samples.
It's very close. I only checked/compared one docbook: mac80211. There is some kind of paragraph end handling difference.
In processing include/net/mac80211.h, struct ieee80211_tx_info, without the patch, it ends with:

Quoted 7 lines

This structure is placed in skb->cb for three uses: (1) mac80211 TX control - mac80211 tells the driver what to do (2) driver internal use (if applicable) (3) TX status information - driver tells mac80211 what happened
The TX control's sta pointer is only valid during the ->tx call, it may be NULL.
and with the patch, those 2 paragraphs are run together:
This structure is placed in skb->cb for three uses: (1) mac80211 TX control - mac80211 tells the driver what to do (2) driver internal use (if applicable) (3) TX status information - driver tells mac80211 what happened The TX control's sta pointer is only valid during the ->tx call, it may be NULL.

Yeah, I forgot to actually collect empty lines in the documentation bodies when changing that conditional. Stupid. I fixed it in the attached version.

---
From: Johannes Weiner <[email protected]>
Subject: kernel-doc: allow multi-line declaration purpose descriptions

Allow the short description after symbol name and dash in a kernel-doc comment to span multiple lines, e.g. like this:

The short description ends with a parameter description, an empty line or the end of the comment block.

Signed-off-by Johannes Weiner <[email protected]>

---

Documentation/kernel-doc-nano-HOWTO.txt +3 -1

index 4d04572..348b9e5 100644
@@ -66,7 +66,9 @@ Example kernel-doc function comment:
  * The longer description can have multiple paragraphs.
  */
 
-The first line, with the short description, must be on a single line.
+The short description following the subject can span multiple lines
+and ends with an @argument description, an empty line or the end of
+the comment block.
 
 The @argument descriptions must begin on the very next line following
 this opening short function description line, with no intervening

scripts/kernel-doc +16 -5

index b52d340..d8b3641 100755
@@ -1995,6 +1995,7 @@ sub process_file($) {
     my $identifier;
     my $func;
     my $descr;
+    my $in_purpose = 0;
     my $initial_section_counter = $section_counter;
 
     if (defined($ENV{'SRCTREE'})) {

@@ -2044,6 +2045,7 @@ sub process_file($) {
 		    $descr =~ s/\s*$//;
 		    $descr =~ s/\s+/ /;
 		    $declaration_purpose = xml_escape($descr);
+		    $in_purpose = 1;
 		} else {
 		    $declaration_purpose = "";
 		}

@@ -2090,6 +2092,7 @@ sub process_file($) {
 		}
 
 		$in_doc_sect = 1;
+		$in_purpose = 0;
 		$contents = $newcontents;
 		if ($contents ne "") {
 		    while ((substr($contents, 0, 1) eq " ") ||

@@ -2119,11 +2122,19 @@ sub process_file($) {
 	    } elsif (/$doc_content/) {
 		# miguel-style comment kludge, look for blank lines after
 		# @parameter line to signify start of description
-		if ($1 eq "" &&
-			($section =~ m/^@/ || $section eq $section_context)) {
-		    dump_section($file, $section, xml_escape($contents));
-		    $section = $section_default;
-		    $contents = "";
+		if ($1 eq "") {
+		    if ($section =~ m/^@/ || $section eq $section_context) {
+			dump_section($file, $section, xml_escape($contents));
+			$section = $section_default;
+			$contents = "";
+		    } else {
+			$contents .= "\n";
+		    }
+		    $in_purpose = 0;
+		} elsif ($in_purpose == 1) {
+		    # Continued declaration purpose
+		    chomp($declaration_purpose);
+		    $declaration_purpose .= " " . $1;
 		} else {
 		    $contents .= $1 . "\n";
 		}

Randy Dunlap

author

2009-08-24 19:57 UTC #12 lore raw

Quoted 31 lines · On Mon, 24 Aug 2009 12:06:54 -0700 (PDT) Johannes Weiner wrote:

Quoted 30 lines · Randy Dunlap
Quoted 6 lines · Johannes Weiner
Quoted 2 lines
Yeah, it's the terminating **/ which matches $doc_cont. I will try to send an updated version this evening.
I got completely rid of the extra re. Just parse a non-empty content line following the declaration purpose immediately as continuation.
Quoted 7 lines
It survives make htmldocs, the scsi_exit_devinfo() doc looks okay and for stuff that had continuation lines before, it does what's expected
- e.g. for the doc of kernel/sched.c::init_sd_power_savings_stats().
It behaves differently for broken docs (mm/page_alloc.c::calculate_zone_inactive_ratio e.g.), but that shouldn't matter.
Right, no problem on that one (for which I sent Andrew a patch some time ago).
Quoted 1 line
I didn't find any other misbehaviour when checking random samples.
It's very close. I only checked/compared one docbook: mac80211. There is some kind of paragraph end handling difference.
In processing include/net/mac80211.h, struct ieee80211_tx_info, without the patch, it ends with:
This structure is placed in skb->cb for three uses: (1) mac80211 TX control - mac80211 tells the driver what to do (2) driver internal use (if applicable) (3) TX status information - driver tells mac80211 what happened
The TX control's sta pointer is only valid during the ->tx call, it may be NULL.

Quoted 7 lines

Quoted 3 lines
and with the patch, those 2 paragraphs are run together:
This structure is placed in skb->cb for three uses: (1) mac80211 TX control - mac80211 tells the driver what to do (2) driver internal use (if applicable) (3) TX status information - driver tells mac80211 what happened The TX control's sta pointer is only valid during the ->tx call, it may be NULL.
Yeah, I forgot to actually collect empty lines in the documentation bodies when changing that conditional. Stupid. I fixed it in the attached version.

Thanks. I had spent some time on it but I hadn't quite found the magical incantation to preserve the exact same output as without the patch, but your patch now does that.

I'll add this to my kernel-doc quilt patch series.

Oh, one question below...

Quoted 76 lines

---
From: Johannes Weiner <[email protected]>
Subject: kernel-doc: allow multi-line declaration purpose descriptions

Allow the short description after symbol name and dash in a kernel-doc comment to span multiple lines, e.g. like this:

The short description ends with a parameter description, an empty line or the end of the comment block.

Signed-off-by Johannes Weiner <[email protected]>

---

Documentation/kernel-doc-nano-HOWTO.txt +3 -1

index 4d04572..348b9e5 100644
@@ -66,7 +66,9 @@ Example kernel-doc function comment:
  * The longer description can have multiple paragraphs.
  */
 
-The first line, with the short description, must be on a single line.
+The short description following the subject can span multiple lines
+and ends with an @argument description, an empty line or the end of
+the comment block.
 
 The @argument descriptions must begin on the very next line following
 this opening short function description line, with no intervening

scripts/kernel-doc +6 -5

index b52d340..d8b3641 100755
@@ -1995,6 +1995,7 @@ sub process_file($) {
     my $identifier;
     my $func;
     my $descr;
+    my $in_purpose = 0;
     my $initial_section_counter = $section_counter;
 
     if (defined($ENV{'SRCTREE'})) {

@@ -2044,6 +2045,7 @@ sub process_file($) {
 		    $descr =~ s/\s*$//;
 		    $descr =~ s/\s+/ /;
 		    $declaration_purpose = xml_escape($descr);
+		    $in_purpose = 1;
 		} else {
 		    $declaration_purpose = "";
 		}

@@ -2090,6 +2092,7 @@ sub process_file($) {
 		}
 
 		$in_doc_sect = 1;
+		$in_purpose = 0;
 		$contents = $newcontents;
 		if ($contents ne "") {
 		    while ((substr($contents, 0, 1) eq " ") ||

@@ -2119,11 +2122,19 @@ sub process_file($) {
 	    } elsif (/$doc_content/) {
 		# miguel-style comment kludge, look for blank lines after
 		# @parameter line to signify start of description
-		if ($1 eq "" &&
-			($section =~ m/^@/ || $section eq $section_context)) {
-		    dump_section($file, $section, xml_escape($contents));
-		    $section = $section_default;
-		    $contents = "";
+		if ($1 eq "") {
+		    if ($section =~ m/^@/ || $section eq $section_context) {
+			dump_section($file, $section, xml_escape($contents));

scripts/kernel-doc sub process_file($) { · line 2137

Quoted 10 lines

scripts/kernel-doc +10 -0

+			$section = $section_default;
+			$contents = "";
+		    } else {
+			$contents .= "\n";
+		    }
+		    $in_purpose = 0;
+		} elsif ($in_purpose == 1) {
+		    # Continued declaration purpose
+		    chomp($declaration_purpose);
+		    $declaration_purpose .= " " . $1;

Why shouldn't this be:

		    $declaration_purpose .= " " . xml_escape($1);

scripts/kernel-doc sub process_file($) { · line 2140

Quoted 3 lines

scripts/kernel-doc +0 -0

 		} else {
 		    $contents .= $1 . "\n";
 		}

---
~Randy
LPC 2009, Sept. 23-25, Portland, Oregon
http://linuxplumbersconf.org/2009/

Johannes Weiner

2009-08-24 20:10 UTC #13 lore raw

Hello Randy,

Quoted 3 lines · Randy Dunlap

On Mon, 24 Aug 2009 12:06:54 -0700 (PDT) Johannes Weiner wrote:
I'll add this to my kernel-doc quilt patch series.

Thanks!

Quoted 26 lines

Oh, one question below...

Quoted 12 lines

scripts/kernel-doc +3 -5

@@ -2119,11 +2122,19 @@ sub process_file($) {
 	    } elsif (/$doc_content/) {
 		# miguel-style comment kludge, look for blank lines after
 		# @parameter line to signify start of description
-		if ($1 eq "" &&
-			($section =~ m/^@/ || $section eq $section_context)) {
-		    dump_section($file, $section, xml_escape($contents));
-		    $section = $section_default;
-		    $contents = "";
+		if ($1 eq "") {
+		    if ($section =~ m/^@/ || $section eq $section_context) {
+			dump_section($file, $section, xml_escape($contents));

scripts/kernel-doc sub process_file($) { · line 2137

Quoted 10 lines

scripts/kernel-doc +10 -0

+			$section = $section_default;
+			$contents = "";
+		    } else {
+			$contents .= "\n";
+		    }
+		    $in_purpose = 0;
+		} elsif ($in_purpose == 1) {
+		    # Continued declaration purpose
+		    chomp($declaration_purpose);
+		    $declaration_purpose .= " " . $1;

Why shouldn't this be:

Quoted 2 lines

		    $declaration_purpose .= " " . xml_escape($1);

Sorry, this should be escaped of course! Could you edit the patch on your side?

Thanks,
Hannes

Randy Dunlap

author

2009-08-24 21:08 UTC #14 lore raw

Quoted 38 lines · On Mon, 24 Aug 2009 22:09:50 +0200 Johannes Weiner wrote:

Hello Randy,

Quoted 3 lines · Randy Dunlap

On Mon, 24 Aug 2009 12:06:54 -0700 (PDT) Johannes Weiner wrote:
I'll add this to my kernel-doc quilt patch series.

Thanks!

Quoted 26 lines

Oh, one question below...

Quoted 12 lines

scripts/kernel-doc +3 -5

@@ -2119,11 +2122,19 @@ sub process_file($) {
 	    } elsif (/$doc_content/) {
 		# miguel-style comment kludge, look for blank lines after
 		# @parameter line to signify start of description
-		if ($1 eq "" &&
-			($section =~ m/^@/ || $section eq $section_context)) {
-		    dump_section($file, $section, xml_escape($contents));
-		    $section = $section_default;
-		    $contents = "";
+		if ($1 eq "") {
+		    if ($section =~ m/^@/ || $section eq $section_context) {
+			dump_section($file, $section, xml_escape($contents));

scripts/kernel-doc sub process_file($) { · line 2137

Quoted 10 lines

scripts/kernel-doc +10 -0

+			$section = $section_default;
+			$contents = "";
+		    } else {
+			$contents .= "\n";
+		    }
+		    $in_purpose = 0;
+		} elsif ($in_purpose == 1) {
+		    # Continued declaration purpose
+		    chomp($declaration_purpose);
+		    $declaration_purpose .= " " . $1;

Why shouldn't this be:

Quoted 2 lines

		    $declaration_purpose .= " " . xml_escape($1);

Quoted 2 lines

Sorry, this should be escaped of course! Could you edit the patch on your side?

Sure, will do.

---
~Randy
LPC 2009, Sept. 23-25, Portland, Oregon
http://linuxplumbersconf.org/2009/