Re: [PATCH] Add kerneldoc for flush_scheduled_work()

[Randy Dunlap <randy.dunlap@oracle.com>]

Johannes Weiner wrote:
> 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;

Hi Hannes,

This looks good in theory, but it doesn't survive a "make htmldocs"
after the patch is applied.

It could be the ending kernel-doc comment characters:
 **/

The problem is in drivers/scsi/scsi_devinfo.c:
/**
 * scsi_dev_info_list_delete - called from scsi.c:exit_scsi to remove the scsi_dev_info_list.
 **/
void scsi_exit_devinfo(void)
{


I'm currently on vacation, but I'll look into it more if you can't
do so.

Thanks.