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

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


-- 
Damien Le Moal
Western Digital Research