[PATCH] scsi: fix func names in kernel-doc

[Randy Dunlap]

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@xxxxxxxxxxx>
>> 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@xxxxxxxxxxx>
>> ---
>>
>> 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@xxxxxxxxxx>

Fix scsi_devinfo.c kernel-doc function names to match
actual function names.

Signed-off-by: Randy Dunlap <randy.dunlap@xxxxxxxxxx>
---
 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@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/