Re: [PATCH] Add kerneldoc for flush_scheduled_work()

[Randy Dunlap <rdunlap@xenotime.net>]

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.

>>  *	@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.

The goal should be to accept what is currently in the kernel source tree IMO,
and this suggestion looks like it would support that.

~Randy