Re: [PATCH] Add kerneldoc for flush_scheduled_work()

[Johannes Weiner <hannes@cmpxchg.org>]

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;