From mboxrd@z Thu Jan  1 00:00:00 1970
From: Ye Xiaolong <xiaolong.ye@intel.com>
Subject: Re: [PATCH] vhost: add doxygen comment to vDPA header
Date: Fri, 12 Oct 2018 04:25:08 +0800
Message-ID: <20181011202508.GA85553@intel.com>
References: <20181010091447.64542-1-xiaolong.ye@intel.com>
 <d398e396-8bc0-9a08-f5ed-9321a3cc7d57@intel.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Cc: dev@dpdk.org, Maxime Coquelin <maxime.coquelin@redhat.com>,
 Tiwei Bie <tiwei.bie@intel.com>,
 Zhihong Wang <zhihong.wang@intel.com>, xiao.w.wang@intel.com
To: Ferruh Yigit <ferruh.yigit@intel.com>
Return-path: <dev-bounces@dpdk.org>
Received: from mga07.intel.com (mga07.intel.com [134.134.136.100])
 by dpdk.org (Postfix) with ESMTP id 2B44E1B49F
 for <dev@dpdk.org>; Thu, 11 Oct 2018 15:38:01 +0200 (CEST)
Content-Disposition: inline
In-Reply-To: <d398e396-8bc0-9a08-f5ed-9321a3cc7d57@intel.com>
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/11, Ferruh Yigit wrote:
>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.
>

Got it, I'll add more descriptions.

><...>
>
>> -/* 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.

Got it.

Thanks,
Xiaolong