linux-kernel - Re: [PATCH] Add kerneldoc for flush_scheduled

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <1250175853.3901.34.camel@mulgrave.site>
Date:	Thu, 13 Aug 2009 10:04:13 -0500
From:	James Bottomley <James.Bottomley@...senPartnership.com>
To:	Johannes Weiner <hannes@...xchg.org>
Cc:	Randy Dunlap <randy.dunlap@...cle.com>, stern@...land.harvard.edu,
	akpm@...ux-foundation.org, apw@...onical.com, mingo@...e.hu,
	linux-kernel@...r.kernel.org, peterz@...radead.org
Subject: Re: [PATCH] Add kerneldoc for flush_scheduled_work()

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


--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/