netdev - Re: [PATCH vhost 1/3] vdpa: address kdoc warnings

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <CACGkMEtObQFH=oQtEmeBdRS504roSTryx9QR5Xww5Lyob6W5Yg@mail.gmail.com>
Date:   Fri, 31 Mar 2023 17:17:47 +0800
From:   Jason Wang <jasowang@...hat.com>
To:     Simon Horman <horms@...nel.org>
Cc:     "Michael S. Tsirkin" <mst@...hat.com>, Eli Cohen <elic@...dia.com>,
        Si-Wei Liu <si-wei.liu@...cle.com>,
        Xie Yongji <xieyongji@...edance.com>,
        Parav Pandit <parav@...dia.com>, kvm@...r.kernel.org,
        virtualization@...ts.linux-foundation.org, netdev@...r.kernel.org
Subject: Re: [PATCH vhost 1/3] vdpa: address kdoc warnings

On Fri, Mar 31, 2023 at 4:58 PM Simon Horman <horms@...nel.org> wrote:
>
> This patch addresses the following minor kdoc problems.
>
> * Incorrect spelling of 'callback' and 'notification'
> * Unrecognised kdoc format for 'struct vdpa_map_file'
> * Missing documentation of 'get_vendor_vq_stats' member of
>   'struct vdpa_config_ops'
> * Missing documentation of 'max_supported_vqs' and 'supported_features'
>   members of 'struct vdpa_mgmt_dev'
>
> Most of these problems were flagged by:
>
>  $ ./scripts/kernel-doc -Werror -none  include/linux/vdpa.h
>  include/linux/vdpa.h:20: warning: expecting prototype for struct vdpa_calllback. Prototype was for struct vdpa_callback instead
>  include/linux/vdpa.h:117: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>   * Corresponding file area for device memory mapping
>  include/linux/vdpa.h:357: warning: Function parameter or member 'get_vendor_vq_stats' not described in 'vdpa_config_ops'
>  include/linux/vdpa.h:518: warning: Function parameter or member 'supported_features' not described in 'vdpa_mgmt_dev'
>  include/linux/vdpa.h:518: warning: Function parameter or member 'max_supported_vqs' not described in 'vdpa_mgmt_dev'
>
> The misspelling of 'notification' was flagged by:
>  $ ./scripts/checkpatch.pl --codespell --showfile --strict -f include/linux/vdpa.h
>  include/linux/vdpa.h:171: CHECK: 'notifcation' may be misspelled - perhaps 'notification'?
>  ...
>
> Signed-off-by: Simon Horman <horms@...nel.org>

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

Thanks

> ---
>  include/linux/vdpa.h | 14 +++++++++++---
>  1 file changed, 11 insertions(+), 3 deletions(-)
>
> diff --git a/include/linux/vdpa.h b/include/linux/vdpa.h
> index 43f59ef10cc9..010321945997 100644
> --- a/include/linux/vdpa.h
> +++ b/include/linux/vdpa.h
> @@ -10,7 +10,7 @@
>  #include <linux/if_ether.h>
>
>  /**
> - * struct vdpa_calllback - vDPA callback definition.
> + * struct vdpa_callback - vDPA callback definition.
>   * @callback: interrupt callback function
>   * @private: the data passed to the callback function
>   */
> @@ -114,7 +114,7 @@ struct vdpa_dev_set_config {
>  };
>
>  /**
> - * Corresponding file area for device memory mapping
> + * struct vdpa_map_file - file area for device memory mapping
>   * @file: vma->vm_file for the mapping
>   * @offset: mapping offset in the vm_file
>   */
> @@ -165,10 +165,16 @@ struct vdpa_map_file {
>   *                             @vdev: vdpa device
>   *                             @idx: virtqueue index
>   *                             @state: pointer to returned state (last_avail_idx)
> + * @get_vendor_vq_stats:       Get the vendor statistics of a device.
> + *                             @vdev: vdpa device
> + *                             @idx: virtqueue index
> + *                             @msg: socket buffer holding stats message
> + *                             @extack: extack for reporting error messages
> + *                             Returns integer: success (0) or error (< 0)
>   * @get_vq_notification:       Get the notification area for a virtqueue (optional)
>   *                             @vdev: vdpa device
>   *                             @idx: virtqueue index
> - *                             Returns the notifcation area
> + *                             Returns the notification area
>   * @get_vq_irq:                        Get the irq number of a virtqueue (optional,
>   *                             but must implemented if require vq irq offloading)
>   *                             @vdev: vdpa device
> @@ -506,6 +512,8 @@ struct vdpa_mgmtdev_ops {
>   * @config_attr_mask: bit mask of attributes of type enum vdpa_attr that
>   *                   management device support during dev_add callback
>   * @list: list entry
> + * @supported_features: features supported by device
> + * @max_supported_vqs: maximum number of virtqueues supported by device
>   */
>  struct vdpa_mgmt_dev {
>         struct device *device;
>
> --
> 2.30.2
>