Re: [PATCH linux-next v2 01/14] vdpa: Follow kdoc comment style

[Jason Wang <jasowang@redhat.com>]

在 2021/4/7 上午1:04, Parav Pandit 写道:
> Follow comment style mentioned in the Writing kernel-doc document [1].
>
> Following warnings are fixed.
> $ scripts/kernel-doc -v -none include/linux/vdpa.h
> include/linux/vdpa.h:11: warning: missing initial short description on line:
>   * vDPA callback definition.
> include/linux/vdpa.h:11: info: Scanning doc for vDPA
> include/linux/vdpa.h:15: warning: cannot understand function prototype: 'struct vdpa_callback '
> include/linux/vdpa.h:21: warning: missing initial short description on line:
>   * vDPA notification area
> include/linux/vdpa.h:21: info: Scanning doc for vDPA
> include/linux/vdpa.h:25: warning: cannot understand function prototype: 'struct vdpa_notification_area '
> include/linux/vdpa.h:31: warning: missing initial short description on line:
>   * vDPA vq_state definition
> include/linux/vdpa.h:31: info: Scanning doc for vDPA
> include/linux/vdpa.h:34: warning: cannot understand function prototype: 'struct vdpa_vq_state '
> include/linux/vdpa.h:41: info: Scanning doc for vDPA device
> include/linux/vdpa.h:51: warning: cannot understand function prototype: 'struct vdpa_device '
> include/linux/vdpa.h:62: info: Scanning doc for vDPA IOVA range
> include/linux/vdpa.h:66: warning: cannot understand function prototype: 'struct vdpa_iova_range '
> include/linux/vdpa.h:72: info: Scanning doc for vDPA_config_ops
> include/linux/vdpa.h:203: warning: cannot understand function prototype: 'struct vdpa_config_ops '
> include/linux/vdpa.h:270: info: Scanning doc for vdpa_driver
> include/linux/vdpa.h:275: warning: cannot understand function prototype: 'struct vdpa_driver '
> include/linux/vdpa.h:347: info: Scanning doc for vdpa_mgmtdev_ops
> include/linux/vdpa.h:360: warning: cannot understand function prototype: 'struct vdpa_mgmtdev_ops '
>
> After this fix:
>
> scripts/kernel-doc -v -none include/linux/vdpa.h
> include/linux/vdpa.h:11: info: Scanning doc for struct vdpa_calllback
> include/linux/vdpa.h:21: info: Scanning doc for struct vdpa_notification_area
> include/linux/vdpa.h:31: info: Scanning doc for struct vdpa_vq_state
> include/linux/vdpa.h:41: info: Scanning doc for struct vdpa_device
> include/linux/vdpa.h:62: info: Scanning doc for struct vdpa_iova_range
> include/linux/vdpa.h:72: info: Scanning doc for struct vdpa_config_ops
> include/linux/vdpa.h:270: info: Scanning doc for struct vdpa_driver
> include/linux/vdpa.h:347: info: Scanning doc for struct vdpa_mgmtdev_ops
>
> [1] https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html
>
> Signed-off-by: Parav Pandit <parav@nvidia.com>
> Reviewed-by: Eli Cohen <elic@nvidia.com>


Acked-by: Jason Wang <jasowang@redhat.com>


> ---
>   include/linux/vdpa.h | 38 +++++++++++++++++++-------------------
>   1 file changed, 19 insertions(+), 19 deletions(-)
>
> diff --git a/include/linux/vdpa.h b/include/linux/vdpa.h
> index 15fa085fab05..37b65ca940cf 100644
> --- a/include/linux/vdpa.h
> +++ b/include/linux/vdpa.h
> @@ -8,7 +8,7 @@
>   #include <linux/vhost_iotlb.h>
>   
>   /**
> - * vDPA callback definition.
> + * struct vdpa_calllback - vDPA callback definition.
>    * @callback: interrupt callback function
>    * @private: the data passed to the callback function
>    */
> @@ -18,7 +18,7 @@ struct vdpa_callback {
>   };
>   
>   /**
> - * vDPA notification area
> + * struct vdpa_notification_area - vDPA notification area
>    * @addr: base address of the notification area
>    * @size: size of the notification area
>    */
> @@ -28,7 +28,7 @@ struct vdpa_notification_area {
>   };
>   
>   /**
> - * vDPA vq_state definition
> + * struct vdpa_vq_state - vDPA vq_state definition
>    * @avail_index: available index
>    */
>   struct vdpa_vq_state {
> @@ -38,7 +38,7 @@ struct vdpa_vq_state {
>   struct vdpa_mgmt_dev;
>   
>   /**
> - * vDPA device - representation of a vDPA device
> + * struct vdpa_device - representation of a vDPA device
>    * @dev: underlying device
>    * @dma_dev: the actual device that is performing DMA
>    * @config: the configuration ops for this device.
> @@ -59,7 +59,7 @@ struct vdpa_device {
>   };
>   
>   /**
> - * vDPA IOVA range - the IOVA range support by the device
> + * struct vdpa_iova_range - the IOVA range support by the device
>    * @first: start of the IOVA range
>    * @last: end of the IOVA range
>    */
> @@ -69,7 +69,7 @@ struct vdpa_iova_range {
>   };
>   
>   /**
> - * vDPA_config_ops - operations for configuring a vDPA device.
> + * struct vdpa_config_ops - operations for configuring a vDPA device.
>    * Note: vDPA device drivers are required to implement all of the
>    * operations unless it is mentioned to be optional in the following
>    * list.
> @@ -267,7 +267,7 @@ int _vdpa_register_device(struct vdpa_device *vdev, int nvqs);
>   void _vdpa_unregister_device(struct vdpa_device *vdev);
>   
>   /**
> - * vdpa_driver - operations for a vDPA driver
> + * struct vdpa_driver - operations for a vDPA driver
>    * @driver: underlying device driver
>    * @probe: the function to call when a device is found.  Returns 0 or -errno.
>    * @remove: the function to call when a device is removed.
> @@ -344,18 +344,18 @@ static inline void vdpa_get_config(struct vdpa_device *vdev, unsigned offset,
>   }
>   
>   /**
> - * vdpa_mgmtdev_ops - vdpa device ops
> - * @dev_add:	Add a vdpa device using alloc and register
> - *		@mdev: parent device to use for device addition
> - *		@name: name of the new vdpa device
> - *		Driver need to add a new device using _vdpa_register_device()
> - *		after fully initializing the vdpa device. Driver must return 0
> - *		on success or appropriate error code.
> - * @dev_del:	Remove a vdpa device using unregister
> - *		@mdev: parent device to use for device removal
> - *		@dev: vdpa device to remove
> - *		Driver need to remove the specified device by calling
> - *		_vdpa_unregister_device().
> + * struct vdpa_mgmtdev_ops - vdpa device ops
> + * @dev_add: Add a vdpa device using alloc and register
> + *	     @mdev: parent device to use for device addition
> + *	     @name: name of the new vdpa device
> + *	     Driver need to add a new device using _vdpa_register_device()
> + *	     after fully initializing the vdpa device. Driver must return 0
> + *	     on success or appropriate error code.
> + * @dev_del: Remove a vdpa device using unregister
> + *	     @mdev: parent device to use for device removal
> + *	     @dev: vdpa device to remove
> + *	     Driver need to remove the specified device by calling
> + *	     _vdpa_unregister_device().
>    */
>   struct vdpa_mgmtdev_ops {
>   	int (*dev_add)(struct vdpa_mgmt_dev *mdev, const char *name);

_______________________________________________
Virtualization mailing list
Virtualization@lists.linux-foundation.org
https://lists.linuxfoundation.org/mailman/listinfo/virtualization