Re: [PATCH] Add kerneldoc for flush_scheduled_work()

James Bottomley
2009-08-13T15:04:18Z

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