* Re: [PATCH] Add kerneldoc for flush_scheduled_work() @ 2009-08-13 12:06 Randy Dunlap 2009-08-13 14:51 ` Johannes Weiner 0 siblings, 1 reply; 15+ messages in thread From: Randy Dunlap @ 2009-08-13 12:06 UTC (permalink / raw) To: hannes; +Cc: stern, James.Bottomley, akpm, apw, mingo, linux-kernel, peterz From: hannes@cmpxchg.org On Thu, Aug 13, 2009 at 09:25:14AM +0200, Ingo Molnar wrote: > > * James Bottomley <James.Bottomley@HansenPartnership.com> wrote: > > > On Wed, 2009-08-12 at 10:13 -0400, Alan Stern wrote: > > > On Wed, 12 Aug 2009, Ingo Molnar wrote: > > > > > > > > And here I was thinking kerneldoc doesn't actually work > > > > > like that, but perhaps Randy fixed it so the initial > > > > > description can line-wrap? > > > > > > 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. > > 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. > 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH] Add kerneldoc for flush_scheduled_work() 2009-08-13 12:06 [PATCH] Add kerneldoc for flush_scheduled_work() Randy Dunlap @ 2009-08-13 14:51 ` Johannes Weiner 2009-08-13 15:04 ` James Bottomley 0 siblings, 1 reply; 15+ messages in thread From: Johannes Weiner @ 2009-08-13 14:51 UTC (permalink / raw) To: Randy Dunlap Cc: stern, James.Bottomley, akpm, apw, mingo, linux-kernel, peterz Hello Randy, On Thu, Aug 13, 2009 at 05:06:28AM -0700, Randy Dunlap wrote: > From: hannes@cmpxchg.org > > On Thu, Aug 13, 2009 at 09:25:14AM +0200, Ingo Molnar wrote: > > > > * James Bottomley <James.Bottomley@HansenPartnership.com> wrote: > > > > > On Wed, 2009-08-12 at 10:13 -0400, Alan Stern wrote: > > > > On Wed, 12 Aug 2009, Ingo Molnar wrote: > > > > > > > > > > And here I was thinking kerneldoc doesn't actually work > > > > > > like that, but perhaps Randy fixed it so the initial > > > > > > description can line-wrap? > > > > > > > > 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. > > > > 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. > > > 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. 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 */ --- 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 --- diff --git a/scripts/kernel-doc b/scripts/kernel-doc index b52d340..e427b0a 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -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') { ^ permalink raw reply related [flat|nested] 15+ messages in thread
* Re: [PATCH] Add kerneldoc for flush_scheduled_work() 2009-08-13 14:51 ` Johannes Weiner @ 2009-08-13 15:04 ` James Bottomley 2009-08-13 16:20 ` Randy Dunlap 0 siblings, 1 reply; 15+ messages in thread From: James Bottomley @ 2009-08-13 15:04 UTC (permalink / raw) To: Johannes Weiner Cc: Randy Dunlap, stern, akpm, apw, mingo, linux-kernel, peterz On Thu, 2009-08-13 at 16:51 +0200, Johannes Weiner wrote: > 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 > * @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 > > --- > > diff --git a/scripts/kernel-doc b/scripts/kernel-doc > index b52d340..e427b0a 100755 > --- a/scripts/kernel-doc > +++ b/scripts/kernel-doc > @@ -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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH] Add kerneldoc for flush_scheduled_work() 2009-08-13 15:04 ` James Bottomley @ 2009-08-13 16:20 ` Randy Dunlap 2009-08-13 18:08 ` Johannes Weiner 0 siblings, 1 reply; 15+ messages in thread From: Randy Dunlap @ 2009-08-13 16:20 UTC (permalink / raw) To: James Bottomley Cc: Johannes Weiner, Randy Dunlap, stern, akpm, apw, mingo, linux-kernel, peterz James Bottomley wrote: > On Thu, 2009-08-13 at 16:51 +0200, Johannes Weiner wrote: >> 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 I like this even less than James does. >> * @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 >> >> --- >> >> diff --git a/scripts/kernel-doc b/scripts/kernel-doc >> index b52d340..e427b0a 100755 >> --- a/scripts/kernel-doc >> +++ b/scripts/kernel-doc >> @@ -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. 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH] Add kerneldoc for flush_scheduled_work() 2009-08-13 16:20 ` Randy Dunlap @ 2009-08-13 18:08 ` Johannes Weiner 2009-08-14 18:23 ` Randy Dunlap 0 siblings, 1 reply; 15+ messages in thread From: Johannes Weiner @ 2009-08-13 18:08 UTC (permalink / raw) To: Randy Dunlap Cc: James Bottomley, Randy Dunlap, stern, akpm, apw, mingo, linux-kernel, peterz On Thu, Aug 13, 2009 at 09:20:54AM -0700, Randy Dunlap wrote: > James Bottomley wrote: > > On Thu, 2009-08-13 at 16:51 +0200, Johannes Weiner wrote: > >> 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 > > I like this even less than James does. Fair enough. > >> diff --git a/scripts/kernel-doc b/scripts/kernel-doc > >> index b52d340..e427b0a 100755 > >> --- a/scripts/kernel-doc > >> +++ b/scripts/kernel-doc > >> @@ -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. 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 */ > 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 <hannes@cmpxchg.org> 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 <hannes@cmpxchg.org> --- diff --git a/scripts/kernel-doc b/scripts/kernel-doc index b52d340..2921aab 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -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; ^ permalink raw reply related [flat|nested] 15+ messages in thread
* Re: [PATCH] Add kerneldoc for flush_scheduled_work() 2009-08-13 18:08 ` Johannes Weiner @ 2009-08-14 18:23 ` Randy Dunlap 2009-08-16 19:13 ` [PATCH] scsi: fix func names in kernel-doc Randy Dunlap 2009-08-18 9:04 ` [PATCH] Add kerneldoc for flush_scheduled_work() Johannes Weiner 0 siblings, 2 replies; 15+ messages in thread From: Randy Dunlap @ 2009-08-14 18:23 UTC (permalink / raw) To: Johannes Weiner Cc: James Bottomley, Randy Dunlap, stern, akpm, apw, mingo, linux-kernel, peterz Johannes Weiner wrote: > On Thu, Aug 13, 2009 at 09:20:54AM -0700, Randy Dunlap wrote: >> James Bottomley wrote: >>> On Thu, 2009-08-13 at 16:51 +0200, Johannes Weiner wrote: >>>> 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 >> I like this even less than James does. > > Fair enough. > >>>> diff --git a/scripts/kernel-doc b/scripts/kernel-doc >>>> index b52d340..e427b0a 100755 >>>> --- a/scripts/kernel-doc >>>> +++ b/scripts/kernel-doc >>>> @@ -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. > > 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 > */ > >> 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 <hannes@cmpxchg.org> > 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 <hannes@cmpxchg.org> > --- > > diff --git a/scripts/kernel-doc b/scripts/kernel-doc > index b52d340..2921aab 100755 > --- a/scripts/kernel-doc > +++ b/scripts/kernel-doc > @@ -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; 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. ^ permalink raw reply [flat|nested] 15+ messages in thread
* [PATCH] scsi: fix func names in kernel-doc 2009-08-14 18:23 ` Randy Dunlap @ 2009-08-16 19:13 ` Randy Dunlap 2009-08-18 9:04 ` [PATCH] Add kerneldoc for flush_scheduled_work() Johannes Weiner 1 sibling, 0 replies; 15+ messages in thread From: Randy Dunlap @ 2009-08-16 19:13 UTC (permalink / raw) To: Johannes Weiner Cc: James Bottomley, stern, akpm, apw, mingo, linux-kernel, peterz Randy Dunlap wrote: > Johannes Weiner wrote: >> On Thu, Aug 13, 2009 at 09:20:54AM -0700, Randy Dunlap wrote: >>> James Bottomley wrote: >>>> On Thu, 2009-08-13 at 16:51 +0200, Johannes Weiner wrote: >>>>> 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 >>> I like this even less than James does. >> Fair enough. >> >>>>> diff --git a/scripts/kernel-doc b/scripts/kernel-doc >>>>> index b52d340..e427b0a 100755 >>>>> --- a/scripts/kernel-doc >>>>> +++ b/scripts/kernel-doc >>>>> @@ -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. >> 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 >> */ >> >>> 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 <hannes@cmpxchg.org> >> 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 <hannes@cmpxchg.org> >> --- >> >> diff --git a/scripts/kernel-doc b/scripts/kernel-doc >> index b52d340..2921aab 100755 >> --- a/scripts/kernel-doc >> +++ b/scripts/kernel-doc >> @@ -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; > > 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. 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 <randy.dunlap@oracle.com> Fix scsi_devinfo.c kernel-doc function names to match actual function names. Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> --- drivers/scsi/scsi_devinfo.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) --- lnx-2631-rc6.orig/drivers/scsi/scsi_devinfo.c +++ lnx-2631-rc6/drivers/scsi/scsi_devinfo.c @@ -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) { ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH] Add kerneldoc for flush_scheduled_work() 2009-08-14 18:23 ` Randy Dunlap 2009-08-16 19:13 ` [PATCH] scsi: fix func names in kernel-doc Randy Dunlap @ 2009-08-18 9:04 ` Johannes Weiner 2009-08-19 22:23 ` Johannes Weiner 1 sibling, 1 reply; 15+ messages in thread From: Johannes Weiner @ 2009-08-18 9:04 UTC (permalink / raw) To: Randy Dunlap Cc: James Bottomley, stern, akpm, apw, mingo, linux-kernel, peterz Hello Randy, On Fri, Aug 14, 2009 at 11:23:55AM -0700, Randy Dunlap wrote: > Johannes Weiner wrote: > > diff --git a/scripts/kernel-doc b/scripts/kernel-doc > > index b52d340..2921aab 100755 > > --- a/scripts/kernel-doc > > +++ b/scripts/kernel-doc > > @@ -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; > > 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. Yeah, it's the terminating **/ which matches $doc_cont. I will try to send an updated version this evening. Hannes ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH] Add kerneldoc for flush_scheduled_work() 2009-08-18 9:04 ` [PATCH] Add kerneldoc for flush_scheduled_work() Johannes Weiner @ 2009-08-19 22:23 ` Johannes Weiner 2009-08-19 23:21 ` Randy Dunlap 0 siblings, 1 reply; 15+ messages in thread From: Johannes Weiner @ 2009-08-19 22:23 UTC (permalink / raw) To: Randy Dunlap Cc: James Bottomley, stern, akpm, apw, mingo, linux-kernel, peterz Hello, On Tue, Aug 18, 2009 at 11:04:19AM +0200, Johannes Weiner wrote: > Hello Randy, > > On Fri, Aug 14, 2009 at 11:23:55AM -0700, Randy Dunlap wrote: > > Johannes Weiner wrote: > > > diff --git a/scripts/kernel-doc b/scripts/kernel-doc > > > index b52d340..2921aab 100755 > > > --- a/scripts/kernel-doc > > > +++ b/scripts/kernel-doc > > > @@ -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; > > > > 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. > > 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 <hannes@cmpxchg.org> 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 <hannes@cmpxchg.org> --- Documentation/kernel-doc-nano-HOWTO.txt | 4 +++- scripts/kernel-doc | 19 ++++++++++++++----- 2 files changed, 17 insertions(+), 6 deletions(-) diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt index 4d04572..348b9e5 100644 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ b/Documentation/kernel-doc-nano-HOWTO.txt @@ -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 diff --git a/scripts/kernel-doc b/scripts/kernel-doc index b52d340..6194ef5 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -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"; } ^ permalink raw reply related [flat|nested] 15+ messages in thread
* Re: [PATCH] Add kerneldoc for flush_scheduled_work() 2009-08-19 22:23 ` Johannes Weiner @ 2009-08-19 23:21 ` Randy Dunlap 2009-08-19 23:27 ` Randy Dunlap 2009-08-24 19:06 ` Johannes Weiner 0 siblings, 2 replies; 15+ messages in thread From: Randy Dunlap @ 2009-08-19 23:21 UTC (permalink / raw) To: Johannes Weiner Cc: James Bottomley, stern, akpm, apw, mingo, linux-kernel, peterz Johannes Weiner wrote: >> 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. Right, no problem on that one (for which I sent Andrew a patch some time ago). > 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: 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. > --- > From: Johannes Weiner <hannes@cmpxchg.org> > 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 <hannes@cmpxchg.org> > --- > Documentation/kernel-doc-nano-HOWTO.txt | 4 +++- > scripts/kernel-doc | 19 ++++++++++++++----- > 2 files changed, 17 insertions(+), 6 deletions(-) > > diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt > index 4d04572..348b9e5 100644 > --- a/Documentation/kernel-doc-nano-HOWTO.txt > +++ b/Documentation/kernel-doc-nano-HOWTO.txt > @@ -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 > diff --git a/scripts/kernel-doc b/scripts/kernel-doc > index b52d340..6194ef5 100755 > --- a/scripts/kernel-doc > +++ b/scripts/kernel-doc > @@ -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"; > } ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH] Add kerneldoc for flush_scheduled_work() 2009-08-19 23:21 ` Randy Dunlap @ 2009-08-19 23:27 ` Randy Dunlap 2009-08-24 19:06 ` Johannes Weiner 1 sibling, 0 replies; 15+ messages in thread From: Randy Dunlap @ 2009-08-19 23:27 UTC (permalink / raw) To: Randy Dunlap Cc: Johannes Weiner, James Bottomley, stern, akpm, apw, mingo, linux-kernel, peterz Randy Dunlap wrote: > Johannes Weiner wrote: >>> 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. > > Right, no problem on that one (for which I sent Andrew a patch some > time ago). > >> 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: > > 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... >> --- >> From: Johannes Weiner <hannes@cmpxchg.org> >> 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 <hannes@cmpxchg.org> >> --- >> Documentation/kernel-doc-nano-HOWTO.txt | 4 +++- >> scripts/kernel-doc | 19 ++++++++++++++----- >> 2 files changed, 17 insertions(+), 6 deletions(-) ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH] Add kerneldoc for flush_scheduled_work() 2009-08-19 23:21 ` Randy Dunlap 2009-08-19 23:27 ` Randy Dunlap @ 2009-08-24 19:06 ` Johannes Weiner 2009-08-24 19:27 ` Randy Dunlap 1 sibling, 1 reply; 15+ messages in thread From: Johannes Weiner @ 2009-08-24 19:06 UTC (permalink / raw) To: Randy Dunlap Cc: James Bottomley, stern, akpm, apw, mingo, linux-kernel, peterz On Wed, Aug 19, 2009 at 04:21:23PM -0700, Randy Dunlap wrote: > Johannes Weiner wrote: > >> 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. > > Right, no problem on that one (for which I sent Andrew a patch some > time ago). > > > 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: > > 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 <hannes@cmpxchg.org> 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 <hannes@cmpxchg.org> --- diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt index 4d04572..348b9e5 100644 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ b/Documentation/kernel-doc-nano-HOWTO.txt @@ -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 diff --git a/scripts/kernel-doc b/scripts/kernel-doc index b52d340..d8b3641 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -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"; } ^ permalink raw reply related [flat|nested] 15+ messages in thread
* Re: [PATCH] Add kerneldoc for flush_scheduled_work() 2009-08-24 19:06 ` Johannes Weiner @ 2009-08-24 19:27 ` Randy Dunlap 2009-08-24 20:09 ` Johannes Weiner 0 siblings, 1 reply; 15+ messages in thread From: Randy Dunlap @ 2009-08-24 19:27 UTC (permalink / raw) To: Johannes Weiner Cc: James Bottomley, stern, akpm, apw, mingo, linux-kernel, peterz On Mon, 24 Aug 2009 12:06:54 -0700 (PDT) Johannes Weiner wrote: > On Wed, Aug 19, 2009 at 04:21:23PM -0700, Randy Dunlap wrote: > > Johannes Weiner wrote: > > >> 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. > > > > Right, no problem on that one (for which I sent Andrew a patch some > > time ago). > > > > > 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: > > > > 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... > --- > From: Johannes Weiner <hannes@cmpxchg.org> > 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 <hannes@cmpxchg.org> > --- > > diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt > index 4d04572..348b9e5 100644 > --- a/Documentation/kernel-doc-nano-HOWTO.txt > +++ b/Documentation/kernel-doc-nano-HOWTO.txt > @@ -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 > diff --git a/scripts/kernel-doc b/scripts/kernel-doc > index b52d340..d8b3641 100755 > --- a/scripts/kernel-doc > +++ b/scripts/kernel-doc > @@ -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; Why shouldn't this be: $declaration_purpose .= " " . xml_escape($1); ? > } else { > $contents .= $1 . "\n"; > } --- ~Randy LPC 2009, Sept. 23-25, Portland, Oregon http://linuxplumbersconf.org/2009/ ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH] Add kerneldoc for flush_scheduled_work() 2009-08-24 19:27 ` Randy Dunlap @ 2009-08-24 20:09 ` Johannes Weiner 2009-08-24 20:25 ` Randy Dunlap 0 siblings, 1 reply; 15+ messages in thread From: Johannes Weiner @ 2009-08-24 20:09 UTC (permalink / raw) To: Randy Dunlap Cc: James Bottomley, stern, akpm, apw, mingo, linux-kernel, peterz Hello Randy, On Mon, Aug 24, 2009 at 12:27:11PM -0700, Randy Dunlap wrote: > 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! > Oh, one question below... > > @@ -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; > > Why shouldn't this be: > $declaration_purpose .= " " . xml_escape($1); > ? Sorry, this should be escaped of course! Could you edit the patch on your side? Thanks, Hannes ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH] Add kerneldoc for flush_scheduled_work() 2009-08-24 20:09 ` Johannes Weiner @ 2009-08-24 20:25 ` Randy Dunlap 0 siblings, 0 replies; 15+ messages in thread From: Randy Dunlap @ 2009-08-24 20:25 UTC (permalink / raw) To: Johannes Weiner Cc: James Bottomley, stern, akpm, apw, mingo, linux-kernel, peterz On Mon, 24 Aug 2009 22:09:50 +0200 Johannes Weiner wrote: > Hello Randy, > > On Mon, Aug 24, 2009 at 12:27:11PM -0700, Randy Dunlap wrote: > > 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! > > > Oh, one question below... > > > > @@ -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; > > > > Why shouldn't this be: > > $declaration_purpose .= " " . xml_escape($1); > > ? > > 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/ ^ permalink raw reply [flat|nested] 15+ messages in thread
end of thread, other threads:[~2009-08-24 21:08 UTC | newest] Thread overview: 15+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2009-08-13 12:06 [PATCH] Add kerneldoc for flush_scheduled_work() Randy Dunlap 2009-08-13 14:51 ` Johannes Weiner 2009-08-13 15:04 ` James Bottomley 2009-08-13 16:20 ` Randy Dunlap 2009-08-13 18:08 ` Johannes Weiner 2009-08-14 18:23 ` Randy Dunlap 2009-08-16 19:13 ` [PATCH] scsi: fix func names in kernel-doc Randy Dunlap 2009-08-18 9:04 ` [PATCH] Add kerneldoc for flush_scheduled_work() Johannes Weiner 2009-08-19 22:23 ` Johannes Weiner 2009-08-19 23:21 ` Randy Dunlap 2009-08-19 23:27 ` Randy Dunlap 2009-08-24 19:06 ` Johannes Weiner 2009-08-24 19:27 ` Randy Dunlap 2009-08-24 20:09 ` Johannes Weiner 2009-08-24 20:25 ` Randy Dunlap
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox