Re: [PATCH] Add kerneldoc for flush_scheduled_work()

Johannes Weiner
2009-08-13T14:51:37Z

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') {