Re: [PATCH] ata: libata: avoid kernel-doc warnings

[Randy Dunlap]

On 7/25/26 7:49 PM, Damien Le Moal wrote:
> On 7/25/26 10:52, Randy Dunlap wrote:
>> Modify comments to prevent kernel-doc warnings:
>> - use "/*" for a non-kernel-doc comment
>> - add a Returns: section for ata_id_major_version()
>>
>> Warning: include/linux/ata.h:770 Cannot find identifier on line:
>>  *
>> Warning: include/linux/ata.h:782 function parameter 'id' not described in 'ata_id_sct_data_tables'
>> Warning: include/linux/ata.h:782 expecting prototype for Word(). Prototype was for ata_id_sct_data_tables() instead
>> Warning: include/linux/ata.h:820 No description found for return value of 'ata_id_major_version'
>>
>> Signed-off-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
>> ---
>> Cc: Damien Le Moal <dlemoal@xxxxxxxxxx>
>> Cc: Niklas Cassel <cassel@xxxxxxxxxx>
>> Cc: linux-ide@xxxxxxxxxxxxxxx
>>
>>  include/linux/ata.h |    5 +++--
>>  1 file changed, 3 insertions(+), 2 deletions(-)
>>
>> --- linux-next-20260722.orig/include/linux/ata.h
>> +++ linux-next-20260722/include/linux/ata.h
>> @@ -767,8 +767,7 @@ static inline bool ata_id_sense_reportin
>>  	return id[ATA_ID_COMMAND_SET_4] & BIT(6);
>>  }
>>  
>> -/**
>> - *
>> +/*
>>   * Word: 206 - SCT Command Transport
>>   *    15:12 - Vendor Specific
>>   *     11:6 - Reserved
>> @@ -815,6 +814,8 @@ static inline bool ata_id_sct_supported(
>>   *
>>   *	The practical impact of this is that ata_id_major_version cannot
>>   *	reliably report on drives below ATA3.
>> + *
>> + *	Returns: major version of ATA drive level or %0 if unknown
> 
> Is the "%0% here intentional ? If yes, why ? Or is it a typo? If it is the
> latter, I can fix when applying.

It indicates to kernel-doc that it's a constant and should be printed
in code/monospace style.
But it's perfectly OK to drop it if you prefer that.

thanks.

>>   */
>>  
>>  static inline unsigned int ata_id_major_version(const u16 *id)
> 
> 

-- 
~Randy