Re: [PATCH 04/11] soc: ti: knav_qmss: Fix kernel-doc Return: tags

[Randy Dunlap <rdunlap@infradead.org>]

On 5/8/26 8:32 AM, Nishanth Menon wrote:
> Fix functions that use inline 'Returns ...' instead of 'Return:'
> kernel-doc comments, producing warnings with W=2:
> 
>   knav_qmss_queue.c:524: No description found for return value
>   of 'knav_queue_open'
> 
> Signed-off-by: Nishanth Menon <nm@ti.com>

Acked-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

> ---
> Cc: Randy Dunlap <rdunlap@infradead.org>
> 
>  drivers/soc/ti/knav_qmss_queue.c | 21 +++++++++++----------
>  1 file changed, 11 insertions(+), 10 deletions(-)
> 
> diff --git a/drivers/soc/ti/knav_qmss_queue.c b/drivers/soc/ti/knav_qmss_queue.c
> index f65658014b05..c3f85052002b 100644
> --- a/drivers/soc/ti/knav_qmss_queue.c
> +++ b/drivers/soc/ti/knav_qmss_queue.c
> @@ -517,7 +517,7 @@ static int knav_queue_flush(struct knav_queue *qh)
>   *			     Subsequent attempts to open a shared queue should
>   *			     also have this flag.
>   *
> - * Returns a handle to the open hardware queue if successful. Use IS_ERR()
> + * Return: handle to the open hardware queue on success. Use IS_ERR()
>   * to check the returned value for error codes.
>   */
>  void *knav_queue_open(const char *name, unsigned id,
> @@ -573,7 +573,7 @@ EXPORT_SYMBOL_GPL(knav_queue_close);
>   * @cmd:			- control commands
>   * @arg:			- command argument
>   *
> - * Returns 0 on success, errno otherwise.
> + * Return: 0 on success, errno otherwise.
>   */
>  int knav_queue_device_control(void *qhandle, enum knav_queue_ctrl_cmd cmd,
>  				unsigned long arg)
> @@ -625,7 +625,7 @@ EXPORT_SYMBOL_GPL(knav_queue_device_control);
>   * @size:		- size of data to push
>   * @flags:		- can be used to pass additional information
>   *
> - * Returns 0 on success, errno otherwise.
> + * Return: 0 on success, errno otherwise.
>   */
>  int knav_queue_push(void *qhandle, dma_addr_t dma,
>  					unsigned size, unsigned flags)
> @@ -646,7 +646,7 @@ EXPORT_SYMBOL_GPL(knav_queue_push);
>   * @qhandle:		- hardware queue handle
>   * @size:		- (optional) size of the data pop'ed.
>   *
> - * Returns a DMA address on success, 0 on failure.
> + * Return: DMA address on success, 0 on failure.
>   */
>  dma_addr_t knav_queue_pop(void *qhandle, unsigned *size)
>  {
> @@ -747,8 +747,8 @@ EXPORT_SYMBOL_GPL(knav_pool_desc_dma_to_virt);
>   * @region_id:		- QMSS region id from which the descriptors are to be
>   *			  allocated.
>   *
> - * Returns a pool handle on success.
> - * Use IS_ERR_OR_NULL() to identify error values on return.
> + * Return: pool handle on success. Use IS_ERR_OR_NULL() to identify
> + * error values on return.
>   */
>  void *knav_pool_create(const char *name,
>  					int num_desc, int region_id)
> @@ -878,7 +878,7 @@ EXPORT_SYMBOL_GPL(knav_pool_destroy);
>   * knav_pool_desc_get()	- Get a descriptor from the pool
>   * @ph:		- pool handle
>   *
> - * Returns descriptor from the pool.
> + * Return: descriptor from the pool on success, error pointer otherwise.
>   */
>  void *knav_pool_desc_get(void *ph)
>  {
> @@ -917,7 +917,7 @@ EXPORT_SYMBOL_GPL(knav_pool_desc_put);
>   * @dma:			- DMA address return pointer
>   * @dma_sz:			- adjusted return pointer
>   *
> - * Returns 0 on success, errno otherwise.
> + * Return: 0 on success, errno otherwise.
>   */
>  int knav_pool_desc_map(void *ph, void *desc, unsigned size,
>  					dma_addr_t *dma, unsigned *dma_sz)
> @@ -942,7 +942,7 @@ EXPORT_SYMBOL_GPL(knav_pool_desc_map);
>   * @dma:			- DMA address of descriptor to unmap
>   * @dma_sz:			- size of descriptor to unmap
>   *
> - * Returns descriptor address on success, Use IS_ERR_OR_NULL() to identify
> + * Return: descriptor address on success. Use IS_ERR_OR_NULL() to identify
>   * error values on return.
>   */
>  void *knav_pool_desc_unmap(void *ph, dma_addr_t dma, unsigned dma_sz)
> @@ -962,7 +962,8 @@ EXPORT_SYMBOL_GPL(knav_pool_desc_unmap);
>  /**
>   * knav_pool_count()	- Get the number of descriptors in pool.
>   * @ph:			- pool handle
> - * Returns number of elements in the pool.
> + *
> + * Return: number of elements in the pool.
>   */
>  int knav_pool_count(void *ph)
>  {

-- 
~Randy