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

[Randy Dunlap]

On 7/25/26 9:14 PM, Damien Le Moal wrote:
> On 7/26/26 12:41, Randy Dunlap wrote:
>>
>>
>> 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.
> 
> Well, given that the patch is all about *not* having that comment as a kernel
> doc, I would prefer staying consistent with this goals and not use kernel docs
> markings. I will remove it if you agree.
> Thanks!

Yes, I see now. Please drop the '%'.
Thanks.

-- 
~Randy