[PATCH] virtio: Add missing kerneldoc for virtio_dma_buf_attach

[PATCH] virtio: Add missing kerneldoc for virtio_dma_buf_attach

[jiang.peng9]

From: Peng Jiang <jiang.peng9@zte.com.cn>

Add kerneldoc for 'virtio_dma_buf_attach' function to fix W=1 warnings:

drivers/virtio/virtio_dma_buf.c:41 function parameter 'dma_buf' not described in 'virtio_dma_buf_attach'
drivers/virtio/virtio_dma_buf.c:41 function parameter 'attach' not described in 'virtio_dma_buf_attach'

Signed-off-by: Peng Jiang <jiang.peng9@zte.com.cn>
---
 drivers/virtio/virtio_dma_buf.c | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/drivers/virtio/virtio_dma_buf.c b/drivers/virtio/virtio_dma_buf.c
index 3fe1d03b0645..18d261ba5197 100644
--- a/drivers/virtio/virtio_dma_buf.c
+++ b/drivers/virtio/virtio_dma_buf.c
@@ -35,7 +35,16 @@ struct dma_buf *virtio_dma_buf_export
 EXPORT_SYMBOL(virtio_dma_buf_export);

 /**
- * virtio_dma_buf_attach - mandatory attach callback for virtio dma-bufs
+ * virtio_dma_buf_attach - Mandatory attach callback for virtio dma-bufs
+ * @dma_buf: Pointer to the shared dma-buf structure
+ * @attach: Pointer to the newly created attachment metadata
+ *
+ * Description: Implements the standard dma-buf attach operation for virtio devices.
+ *              Retrieves virtio-specific operations through container_of macro,
+ *              then invokes device-specific attach callback if present.
+ *              This enables virtio devices to participate in dma-buf sharing.
+ *
+ * Return: 0 on success, error code on failure
  */
 int virtio_dma_buf_attach(struct dma_buf *dma_buf,
                          struct dma_buf_attachment *attach)
-- 
2.25.1

Re: [PATCH] virtio: Add missing kerneldoc for virtio_dma_buf_attach

[Krzysztof Kozlowski]

On 04/07/2025 09:20, jiang.peng9@zte.com.cn wrote:
> From: Peng Jiang <jiang.peng9@zte.com.cn>
> 
> Add kerneldoc for 'virtio_dma_buf_attach' function to fix W=1 warnings:
> 
> drivers/virtio/virtio_dma_buf.c:41 function parameter 'dma_buf' not described in 'virtio_dma_buf_attach'
> drivers/virtio/virtio_dma_buf.c:41 function parameter 'attach' not described in 'virtio_dma_buf_attach'
> 
> Signed-off-by: Peng Jiang <jiang.peng9@zte.com.cn>
> ---
>  drivers/virtio/virtio_dma_buf.c | 11 ++++++++++-
>  1 file changed, 10 insertions(+), 1 deletion(-)
> 
> diff --git a/drivers/virtio/virtio_dma_buf.c b/drivers/virtio/virtio_dma_buf.c
> index 3fe1d03b0645..18d261ba5197 100644
> --- a/drivers/virtio/virtio_dma_buf.c
> +++ b/drivers/virtio/virtio_dma_buf.c
> @@ -35,7 +35,16 @@ struct dma_buf *virtio_dma_buf_export
>  EXPORT_SYMBOL(virtio_dma_buf_export);
> 
>  /**
> - * virtio_dma_buf_attach - mandatory attach callback for virtio dma-bufs
> + * virtio_dma_buf_attach - Mandatory attach callback for virtio dma-bufs

Read kernel-doc.rst. Missing ()

> + * @dma_buf: Pointer to the shared dma-buf structure
> + * @attach: Pointer to the newly created attachment metadata
> + *
> + * Description: Implements the standard dma-buf attach operation for virtio devices.

That's not kerneldoc. Which part of kernel-doc document documents such
syntax?


> + *              Retrieves virtio-specific operations through container_of macro,
> + *              then invokes device-specific attach callback if present.
Best regards,
Krzysztof

Re: [PATCH] virtio: Add missing kerneldoc for virtio_dma_buf_attach

[jiang.peng9]

> > diff --git a/drivers/virtio/virtio_dma_buf.c b/drivers/virtio/> virtio_dma_buf.c
> > index 3fe1d03b0645..18d261ba5197 100644
> > --- a/drivers/virtio/virtio_dma_buf.c
> > +++ b/drivers/virtio/virtio_dma_buf.c
> > @@ -35,7 +35,16 @@ struct dma_buf *virtio_dma_buf_export
> >  EXPORT_SYMBOL(virtio_dma_buf_export);
> >
> >  /**
> > - * virtio_dma_buf_attach - mandatory attach callback for virtio dma-bufs
> > + * virtio_dma_buf_attach - Mandatory attach callback for virtio dma-bufs
>
> Read kernel-doc.rst. Missing ()
>
> > + * @dma_buf: Pointer to the shared dma-buf structure
> > + * @attach: Pointer to the newly created attachment metadata
> > + *
> > + * Description: Implements the standard dma-buf attach operation for > virtio devices.
>
> That's not kerneldoc. Which part of kernel-doc document documents such
> syntax?

Thanks so much for your time and feedback! I’ve made two specific fixes based on your notes:  

Added () to the function name in the kerneldoc comment (e.g., virtio_dma_buf_attach() instead of virtio_dma_buf_attach).
Removed the redundant "Description:" label and simplified the explanation. 

Let me know if you need anything else in the meantime!  

Best regards,
Peng