Re: [PATCH] Add kerneldoc for flush_scheduled_work()

Johannes Weiner
2009-08-13T18:09:37Z

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;