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]

Date:	Thu, 13 Aug 2009 09:20:54 -0700
From:	Randy Dunlap <rdunlap@...otime.net>
To:	James Bottomley <James.Bottomley@...senPartnership.com>
CC:	Johannes Weiner <hannes@...xchg.org>,
	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()

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
--
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/