From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752816AbZHMSJh (ORCPT ); Thu, 13 Aug 2009 14:09:37 -0400 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S1752360AbZHMSJh (ORCPT ); Thu, 13 Aug 2009 14:09:37 -0400 Received: from cmpxchg.org ([85.214.51.133]:46159 "EHLO cmpxchg.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752260AbZHMSJg (ORCPT ); Thu, 13 Aug 2009 14:09:36 -0400 Date: Thu, 13 Aug 2009 20:08:56 +0200 From: Johannes Weiner To: Randy Dunlap Cc: James Bottomley , Randy Dunlap , stern@rowland.harvard.edu, akpm@linux-foundation.org, apw@canonical.com, mingo@elte.hu, linux-kernel@vger.kernel.org, peterz@infradead.org Subject: Re: [PATCH] Add kerneldoc for flush_scheduled_work() Message-ID: <20090813180856.GB26020@cmpxchg.org> References: <13a78aa7-dd27-49d9-8164-d6e802bd4796@default> <20090813145106.GA25333@cmpxchg.org> <1250175853.3901.34.camel@mulgrave.site> <4A843D66.1060407@xenotime.net> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <4A843D66.1060407@xenotime.net> Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.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 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 --- 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;