Explicitly describe every parameter rather than summarizing.

Signed-off-by: John Levon <john.levon@nutanix.com>
---
 include/hw/vfio/vfio-device.h | 52 +++++++++++++++++++++++++++++------
 1 file changed, 43 insertions(+), 9 deletions(-)

diff --git a/include/hw/vfio/vfio-device.h b/include/hw/vfio/vfio-device.h
index f39259406b..d45e5a68a2 100644
--- a/include/hw/vfio/vfio-device.h
+++ b/include/hw/vfio/vfio-device.h
@@ -168,14 +168,25 @@ struct VFIODeviceIOOps {
      * @device_feature
      *
      * Fill in feature info for the given device.
+     *
+     * @vdev: #VFIODevice to use
+     * @feat: feature information to fill in
+     *
+     * Returns 0 on success or -errno.
      */
-    int (*device_feature)(VFIODevice *vdev, struct vfio_device_feature *);
+    int (*device_feature)(VFIODevice *vdev, struct vfio_device_feature *feat);
 
     /**
      * @get_region_info
      *
-     * Fill in @info (and optionally @fd) with information on the region given
-     * by @info->index.
+     * Get the information for a given region on the device.
+     *
+     * @vdev: #VFIODevice to use
+     * @info: set @info->index to the region index to look up; the rest of the
+     *        struct will be filled in on success
+     * @fd: pointer to the fd for the region; will be -1 if not found
+     *
+     * Returns 0 on success or -errno.
      */
     int (*get_region_info)(VFIODevice *vdev,
                            struct vfio_region_info *info, int *fd);
@@ -183,22 +194,38 @@ struct VFIODeviceIOOps {
     /**
      * @get_irq_info
      *
-     * Fill in @irq with information on the IRQ given by @info->index.
+     * @vdev: #VFIODevice to use
+     * @irq: set @irq->index to the IRQ index to look up; the rest of the struct
+     *       will be filled in on success
+     *
+     * Returns 0 on success or -errno.
      */
     int (*get_irq_info)(VFIODevice *vdev, struct vfio_irq_info *irq);
 
     /**
      * @set_irqs
      *
-     * Configure IRQs as defined by @irqs.
+     * Configure IRQs.
+     *
+     * @vdev: #VFIODevice to use
+     * @irqs: IRQ configuration as defined by VFIO docs.
+     *
+     * Returns 0 on success or -errno.
      */
     int (*set_irqs)(VFIODevice *vdev, struct vfio_irq_set *irqs);
 
     /**
      * @region_read
      *
-     * Read @size bytes from the region @nr at offset @off into the buffer
-     * @data.
+     * Read part of a region.
+     *
+     * @vdev: #VFIODevice to use
+     * @nr: region index
+     * @off: offset within the region
+     * @size: size in bytes to read
+     * @data: buffer to read into
+     *
+     * Returns number of bytes read on success or -errno.
      */
     int (*region_read)(VFIODevice *vdev, uint8_t nr, off_t off, uint32_t size,
                        void *data);
@@ -206,8 +233,15 @@ struct VFIODeviceIOOps {
     /**
      * @region_write
      *
-     * Write @size bytes to the region @nr at offset @off from the buffer
-     * @data; if @post, the write is posted.
+     * Write part of a region.
+     *
+     * @vdev: #VFIODevice to use
+     * @nr: region index
+     * @off: offset within the region
+     * @size: size in bytes to write
+     * @data: buffer to write from
+     *
+     * Returns number of bytes write on success or -errno.
      */
     int (*region_write)(VFIODevice *vdev, uint8_t nr, off_t off, uint32_t size,
                         void *data, bool post);
-- 
2.43.0

On 6/11/25 12:47, John Levon wrote:
> Explicitly describe every parameter rather than summarizing.
> 
> Signed-off-by: John Levon <john.levon@nutanix.com>


Reviewed-by: Cédric Le Goater <clg@redhat.com>

Applied to vfio-next.

Thanks,

C.


> ---
>   include/hw/vfio/vfio-device.h | 52 +++++++++++++++++++++++++++++------
>   1 file changed, 43 insertions(+), 9 deletions(-)
> 
> diff --git a/include/hw/vfio/vfio-device.h b/include/hw/vfio/vfio-device.h
> index f39259406b..d45e5a68a2 100644
> --- a/include/hw/vfio/vfio-device.h
> +++ b/include/hw/vfio/vfio-device.h
> @@ -168,14 +168,25 @@ struct VFIODeviceIOOps {
>        * @device_feature
>        *
>        * Fill in feature info for the given device.
> +     *
> +     * @vdev: #VFIODevice to use
> +     * @feat: feature information to fill in
> +     *
> +     * Returns 0 on success or -errno.
>        */
> -    int (*device_feature)(VFIODevice *vdev, struct vfio_device_feature *);
> +    int (*device_feature)(VFIODevice *vdev, struct vfio_device_feature *feat);
>   
>       /**
>        * @get_region_info
>        *
> -     * Fill in @info (and optionally @fd) with information on the region given
> -     * by @info->index.
> +     * Get the information for a given region on the device.
> +     *
> +     * @vdev: #VFIODevice to use
> +     * @info: set @info->index to the region index to look up; the rest of the
> +     *        struct will be filled in on success
> +     * @fd: pointer to the fd for the region; will be -1 if not found
> +     *
> +     * Returns 0 on success or -errno.
>        */
>       int (*get_region_info)(VFIODevice *vdev,
>                              struct vfio_region_info *info, int *fd);
> @@ -183,22 +194,38 @@ struct VFIODeviceIOOps {
>       /**
>        * @get_irq_info
>        *
> -     * Fill in @irq with information on the IRQ given by @info->index.
> +     * @vdev: #VFIODevice to use
> +     * @irq: set @irq->index to the IRQ index to look up; the rest of the struct
> +     *       will be filled in on success
> +     *
> +     * Returns 0 on success or -errno.
>        */
>       int (*get_irq_info)(VFIODevice *vdev, struct vfio_irq_info *irq);
>   
>       /**
>        * @set_irqs
>        *
> -     * Configure IRQs as defined by @irqs.
> +     * Configure IRQs.
> +     *
> +     * @vdev: #VFIODevice to use
> +     * @irqs: IRQ configuration as defined by VFIO docs.
> +     *
> +     * Returns 0 on success or -errno.
>        */
>       int (*set_irqs)(VFIODevice *vdev, struct vfio_irq_set *irqs);
>   
>       /**
>        * @region_read
>        *
> -     * Read @size bytes from the region @nr at offset @off into the buffer
> -     * @data.
> +     * Read part of a region.
> +     *
> +     * @vdev: #VFIODevice to use
> +     * @nr: region index
> +     * @off: offset within the region
> +     * @size: size in bytes to read
> +     * @data: buffer to read into
> +     *
> +     * Returns number of bytes read on success or -errno.
>        */
>       int (*region_read)(VFIODevice *vdev, uint8_t nr, off_t off, uint32_t size,
>                          void *data);
> @@ -206,8 +233,15 @@ struct VFIODeviceIOOps {
>       /**
>        * @region_write
>        *
> -     * Write @size bytes to the region @nr at offset @off from the buffer
> -     * @data; if @post, the write is posted.
> +     * Write part of a region.
> +     *
> +     * @vdev: #VFIODevice to use
> +     * @nr: region index
> +     * @off: offset within the region
> +     * @size: size in bytes to write
> +     * @data: buffer to write from
> +     *
> +     * Returns number of bytes write on success or -errno.
>        */
>       int (*region_write)(VFIODevice *vdev, uint8_t nr, off_t off, uint32_t size,
>                           void *data, bool post);