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

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

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!

-- 
Damien Le Moal
Western Digital Research