[PATCH v3] virtio: Update kerneldoc in drivers/virtio/virtio_dma_buf.c

[PATCH v3] virtio: Update kerneldoc in drivers/virtio/virtio_dma_buf.c

[jiang.peng9]

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

Re: [PATCH v3] virtio: Update kerneldoc in drivers/virtio/virtio_dma_buf.c

[Michael S. Tsirkin]

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

Re: [PATCH v3] virtio: Update kerneldoc in drivers/virtio/virtio_dma_buf.c

[jiang.peng9]

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

Re: Re: [PATCH v3] virtio: Update kerneldoc in drivers/virtio/virtio_dma_buf.c

[WangYuli]

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

Re: [PATCH v3] virtio: Update kerneldoc in drivers/virtio/virtio_dma_buf.c

[jiang.peng9]

Hi Yuli,

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

Best regards,
Peng Jiang