Re: [PATCH] Add kerneldoc for flush_scheduled_work()

[James Bottomley <James.Bottomley@HansenPartnership.com>]

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

>  *	@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*(.+)';

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.

James