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

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

[Randy Dunlap]

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
  */
 
 static inline unsigned int ata_id_major_version(const u16 *id)

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

[Damien Le Moal]

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.

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


-- 
Damien Le Moal
Western Digital Research

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@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.

thanks.

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

-- 
~Randy

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

[Damien Le Moal]

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

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@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 '%'.
Thanks.

-- 
~Randy

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

[Damien Le Moal]

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

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

[Damien Le Moal]

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>

Applied to for-7.2-fixes with the comment tweak we discussed. Thanks!

-- 
Damien Le Moal
Western Digital Research