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

Fix kernel-doc descriptions in virtio_dma_buf.c 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 | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/drivers/virtio/virtio_dma_buf.c b/drivers/virtio/virtio_dma_buf.c
index 3fe1d03b0645..986cc73c503f 100644
--- a/drivers/virtio/virtio_dma_buf.c
+++ b/drivers/virtio/virtio_dma_buf.c
@@ -16,6 +16,8 @@
  * This wraps dma_buf_export() to allow virtio drivers to create a dma-buf
  * for an virtio exported object that can be queried by other virtio drivers
  * for the object's UUID.
+ *
+ * Returns: dma-buf pointer on success, ERR_PTR on failure.
  */
 struct dma_buf *virtio_dma_buf_export
        (const struct dma_buf_export_info *exp_info)
@@ -36,6 +38,14 @@ EXPORT_SYMBOL(virtio_dma_buf_export);

 /**
  * virtio_dma_buf_attach - mandatory attach callback for virtio dma-bufs
+ * @dma_buf: DMA buffer being attached to a device
+ * @attach: Attachment metadata for the device-dma_buf association
+ *
+ * Allows virtio devices to perform device-specific setup when a DMA buffer
+ * is attached to a device. This is part of the DMA-BUF sharing mechanism
+ * that enables virtio devices to interoperate with other subsystems.
+ *
+ * Returns: 0 on success, negative on failure.
  */
 int virtio_dma_buf_attach(struct dma_buf *dma_buf,
                          struct dma_buf_attachment *attach)
-- 
2.25.1

On Thu, Jul 17, 2025 at 10:41:59AM +0800, jiang.peng9@zte.com.cn wrote:
> From: Peng Jiang <jiang.peng9@zte.com.cn>
> 
> Fix kernel-doc descriptions in virtio_dma_buf.c 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 | 10 ++++++++++
>  1 file changed, 10 insertions(+)
> 
> diff --git a/drivers/virtio/virtio_dma_buf.c b/drivers/virtio/virtio_dma_buf.c
> index 3fe1d03b0645..986cc73c503f 100644
> --- a/drivers/virtio/virtio_dma_buf.c
> +++ b/drivers/virtio/virtio_dma_buf.c
> @@ -16,6 +16,8 @@
>   * This wraps dma_buf_export() to allow virtio drivers to create a dma-buf
>   * for an virtio exported object that can be queried by other virtio drivers
>   * for the object's UUID.
> + *
> + * Returns: dma-buf pointer on success, ERR_PTR on failure.

Most people write "dmabuf".


>   */
>  struct dma_buf *virtio_dma_buf_export
>         (const struct dma_buf_export_info *exp_info)
> @@ -36,6 +38,14 @@ EXPORT_SYMBOL(virtio_dma_buf_export);
> 
>  /**
>   * virtio_dma_buf_attach - mandatory attach callback for virtio dma-bufs
> + * @dma_buf: DMA buffer being attached to a device

And here it's different for some reason.

> + * @attach: Attachment metadata for the device-dma_buf association

and here in a third form.

> + *
> + * Allows virtio devices to perform device-specific setup when a DMA buffer
> + * is attached to a device. This is part of the DMA-BUF sharing mechanism
> + * that enables virtio devices to interoperate with other subsystems.

I'm sorry this is just empty of content.
I can not shake the feeling this is AI written.
If we wanted AI to document all APIs in this way, I'd just script it.

> + *
> + * Returns: 0 on success, negative on failure.

This one is ok.

>   */
>  int virtio_dma_buf_attach(struct dma_buf *dma_buf,
>                           struct dma_buf_attachment *attach)
> -- 
> 2.25.1

> > diff --git a/drivers/virtio/virtio_dma_buf.c b/drivers/virtio/virtio_dma_buf.c
> > index 3fe1d03b0645..986cc73c503f 100644
> > --- a/drivers/virtio/virtio_dma_buf.c
> > +++ b/drivers/virtio/virtio_dma_buf.c
> > @@ -16,6 +16,8 @@
> >   * This wraps dma_buf_export() to allow virtio drivers to create a dma-buf
> >   * for an virtio exported object that can be queried by other virtio drivers
> >   * for the object's UUID.
> > + *
> > + * Returns: dma-buf pointer on success, ERR_PTR on failure.
>
> Most people write "dmabuf".

Thanks for pointing this out. In virtio_dma_buf.c specifically, "dma-buf" appears more frequently throughout the file.
 For consistency within this file, I'll keep using "dma-buf" in these docs.

> >   */
> >  struct dma_buf *virtio_dma_buf_export
> >         (const struct dma_buf_export_info *exp_info)
> > @@ -36,6 +38,14 @@ EXPORT_SYMBOL(virtio_dma_buf_export);
> >
> >  /**
> >   * virtio_dma_buf_attach - mandatory attach callback for virtio dma-bufs
> > + * @dma_buf: DMA buffer being attached to a device
>
> And here it's different for some reason.
>
> > + * @attach: Attachment metadata for the device-dma_buf association
>
> and here in a third form.

Thanks for catching the inconsistency. Here are the standardized parameter descriptions:
  @dma_buf: dma-buf being attached to a device
  @attach: Attachment metadata for the dma-buf association

> > + *
> > + * Allows virtio devices to perform device-specific setup when a DMA buffer
> > + * is attached to a device. This is part of the DMA-BUF sharing mechanism
> > + * that enables virtio devices to interoperate with other subsystems.
>
> I'm sorry this is just empty of content.
> I can not shake the feeling this is AI written.
> If we wanted AI to document all APIs in this way, I'd just script it.

I‘ll remove the generic description.

Best regards,
Peng Jiang

Hi Peng Jiang,

Please feel free to add "Reviewed-by: WangYuli <wangyuli@uniontech.com>"
to your patch v4. [1]

[1]. https://lore.kernel.org/all/20250716094357-mutt-send-email-mst@kernel.org/

Thanks,
--
WangYuli

Hi Yuli,

Thank you for notifying me about this. Please proceed with your patch directly - I have no concerns.

Best regards,
Peng Jiang