Messages in this thread Patch in this message | | | Date | Thu, 13 Aug 2009 16:51:06 +0200 | From | Johannes Weiner <> | Subject | Re: [PATCH] Add kerneldoc for flush_scheduled_work() |
| |
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') {
| |