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

[Damien Le Moal <dlemoal@kernel.org>]

On 7/26/26 13:19, Randy Dunlap wrote:
> 
> 
> 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@infradead.org>
>>>>> ---
>>>>> Cc: Damien Le Moal <dlemoal@kernel.org>
>>>>> Cc: Niklas Cassel <cassel@kernel.org>
>>>>> Cc: linux-ide@vger.kernel.org
>>>>>
>>>>>  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 '%'.

I completely misread this patch: the %0 is fine since that is in the kdoc for
ata_id_major_version(), so all good. My apologies for the noise.



-- 
Damien Le Moal
Western Digital Research