| 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
| ||
|
Date: Sun, 16 Aug 2009 12:13:09 -0700
From: Randy Dunlap <randy.dunlap@...cle.com>
To: Johannes Weiner <hannes@...xchg.org>
CC: James Bottomley <James.Bottomley@...senPartnership.com>,
stern@...land.harvard.edu, akpm@...ux-foundation.org,
apw@...onical.com, mingo@...e.hu, linux-kernel@...r.kernel.org,
peterz@...radead.org
Subject: [PATCH] scsi: fix func names in kernel-doc
Randy Dunlap wrote:
> Johannes Weiner wrote:
>> On Thu, Aug 13, 2009 at 09:20:54AM -0700, Randy Dunlap wrote:
>>> 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.
>> Fair enough.
>>
>>>>> 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 \s comes from $doc_com already. We need the [^\s] as you said to
>> skip empty lines but also the slash for this one:
>>
>> * @foo: yada
>> */
>>
>>> The goal should be to accept what is currently in the kernel source tree IMO,
>>> and this suggestion looks like it would support that.
>> Yeah. I also noticed that multi-line blocks starting with @foo: are
>> already handled, making the indirect referencing unnecessary. The
>> result is a bit simpler and more straight-forward, I think.
>>
>> Hannes
>>
>> --
>> From: Johannes Weiner <hannes@...xchg.org>
>> Subject: kernel-doc: allow multi-line declaration purpose descriptions
>>
>> Allow the short description after symbol name and dash in a kernel-doc
>> comment to span multiple lines, like this:
>>
>> /**
>> * unmap_mapping_range - unmap the portion of all mmaps in the
>> * specified address_space corresponding to the specified
>> * page range in the underlying file.
>> * @mapping: the address space containing mmaps to be unmapped.
>> * ...
>> */
>>
>> The short description ends with a newline, a parameter description or
>> the end of the comment block.
>>
>> Signed-off-by: Johannes Weiner <hannes@...xchg.org>
>> ---
>>
>> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
>> index b52d340..2921aab 100755
>> --- a/scripts/kernel-doc
>> +++ b/scripts/kernel-doc
>> @@ -281,6 +281,7 @@ my $doc_end = '\*/';
>> my $doc_com = '\s*\*\s*';
>> my $doc_decl = $doc_com . '(\w+)';
>> my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
>> +my $doc_cont = $doc_com . '([^@/\s].*)';
>> my $doc_content = $doc_com . '(.*)';
>> my $doc_block = $doc_com . 'DOC:\s*(.*)?';
>>
>> @@ -1995,6 +1996,7 @@ sub process_file($) {
>> my $identifier;
>> my $func;
>> my $descr;
>> + my $in_purpose = 0;
>> my $initial_section_counter = $section_counter;
>>
>> if (defined($ENV{'SRCTREE'})) {
>> @@ -2044,6 +2046,7 @@ sub process_file($) {
>> $descr =~ s/\s*$//;
>> $descr =~ s/\s+/ /;
>> $declaration_purpose = xml_escape($descr);
>> + $in_purpose = 1;
>> } else {
>> $declaration_purpose = "";
>> }
>> @@ -2075,7 +2078,12 @@ sub process_file($) {
>> ++$warnings;
>> $state = 0;
>> }
>> + } elsif ($in_purpose == 1 && /$doc_cont/o) {
>> + # continued description
>> + chomp($declaration_purpose);
>> + $declaration_purpose .= " " . $1;
>> } elsif ($state == 2) { # look for head: lines, and include content
>> + $in_purpose = 0;
>> if (/$doc_sect/o) {
>> $newsection = $1;
>> $newcontents = $2;
>
> Hi Hannes,
>
> This looks good in theory, but it doesn't survive a "make htmldocs"
> after the patch is applied.
>
> It could be the ending kernel-doc comment characters:
> **/
>
> The problem is in drivers/scsi/scsi_devinfo.c:
> /**
> * scsi_dev_info_list_delete - called from scsi.c:exit_scsi to remove the scsi_dev_info_list.
> **/
> void scsi_exit_devinfo(void)
> {
>
>
> I'm currently on vacation, but I'll look into it more if you can't
> do so.
Duh. James, the kernel-doc func name and actual func name don't match.
Here's a patch for that and one other mismatched func name.
-----
From: Randy Dunlap <randy.dunlap@...cle.com>
Fix scsi_devinfo.c kernel-doc function names to match
actual function names.
Signed-off-by: Randy Dunlap <randy.dunlap@...cle.com>
---
drivers/scsi/scsi_devinfo.c | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
--- lnx-2631-rc6.orig/drivers/scsi/scsi_devinfo.c
+++ lnx-2631-rc6/drivers/scsi/scsi_devinfo.c
@@ -454,7 +454,7 @@ int scsi_get_device_flags(struct scsi_de
/**
- * get_device_flags_keyed - get device specific flags from the dynamic device list.
+ * scsi_get_device_flags_keyed - get device specific flags from the dynamic device list
* @sdev: &scsi_device to get flags for
* @vendor: vendor name
* @model: model name
@@ -685,7 +685,7 @@ MODULE_PARM_DESC(default_dev_flags,
"scsi default device flag integer value");
/**
- * scsi_dev_info_list_delete - called from scsi.c:exit_scsi to remove the scsi_dev_info_list.
+ * scsi_exit_devinfo - remove /proc/scsi/device_info & the scsi_dev_info_list
**/
void scsi_exit_devinfo(void)
{
--
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/
Powered by blists - more mailing lists