From mboxrd@z Thu Jan  1 00:00:00 1970
From: Ferruh Yigit <ferruh.yigit@intel.com>
Subject: Re: [PATCH] vhost: add doxygen comment to vDPA header
Date: Thu, 11 Oct 2018 14:28:25 +0100
Message-ID: <d398e396-8bc0-9a08-f5ed-9321a3cc7d57@intel.com>
References: <20181010091447.64542-1-xiaolong.ye@intel.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit
Cc: xiao.w.wang@intel.com
To: Xiaolong Ye <xiaolong.ye@intel.com>, dev@dpdk.org,
 Maxime Coquelin <maxime.coquelin@redhat.com>, Tiwei Bie
 <tiwei.bie@intel.com>, Zhihong Wang <zhihong.wang@intel.com>
Return-path: <dev-bounces@dpdk.org>
Received: from mga04.intel.com (mga04.intel.com [192.55.52.120])
 by dpdk.org (Postfix) with ESMTP id 908E01B50D
 for <dev@dpdk.org>; Thu, 11 Oct 2018 15:28:36 +0200 (CEST)
In-Reply-To: <20181010091447.64542-1-xiaolong.ye@intel.com>
Content-Language: en-US
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
 <mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
 <mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org
Sender: "dev" <dev-bounces@dpdk.org>

On 10/10/2018 10:14 AM, Xiaolong Ye wrote:
> As APIs in rte_vdpa.h are public, we need to add doxygen comments
> to all APIs and structures.
> 
> Signed-off-by: Xiaolong Ye <xiaolong.ye@intel.com>

<...>

> @@ -29,6 +32,9 @@ struct rte_vdpa_dev_addr {
>  	};
>  };
>  
> +/**
> + * vdpa device operations
> + */
>  struct rte_vdpa_dev_ops {
>  	/* Get capabilities of this device */
>  	int (*get_queue_num)(int did, uint32_t *queue_num);

Can you please document all fields of the structs?
This is part of public API and needs to be documented properly, if possible more
detail on struct documentation will be good.

<...>

> -/* Register a vdpa device, return did if successful, -1 on failure */
> +/**
> + * Register a vdpa device
> + *
> + * @param addr
> + *  the vdpa device address
> + * @parm ops
> + *  the vdpa device operations
> + * @return
> + *  device id on success, -1 on failure
> + */
>  int __rte_experimental
>  rte_vdpa_register_device(struct rte_vdpa_dev_addr *addr,
>  		struct rte_vdpa_dev_ops *ops);

For experimental APIs we tend to add following into function comment:
  * @warning
  * @b EXPERIMENTAL: this API may change without prior notice

Please check lib/librte_member/rte_member.h for samples.