From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <xiaolong.ye@intel.com>
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)
X-Amp-Result: UNSCANNABLE
X-Amp-File-Uploaded: False
Received: from fmsmga005.fm.intel.com ([10.253.24.32])
 by orsmga105.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384;
 11 Oct 2018 06:38:00 -0700
X-ExtLoop1: 1
X-IronPort-AV: E=Sophos;i="5.54,368,1534834800"; d="scan'208";a="270473709"
Received: from yexl-server.sh.intel.com (HELO localhost) ([10.67.110.207])
 by fmsmga005.fm.intel.com with ESMTP; 11 Oct 2018 06:37:58 -0700
Date: Fri, 12 Oct 2018 04:25:08 +0800
From: Ye Xiaolong <xiaolong.ye@intel.com>
To: Ferruh Yigit <ferruh.yigit@intel.com>
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
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
Content-Disposition: inline
In-Reply-To: <d398e396-8bc0-9a08-f5ed-9321a3cc7d57@intel.com>
User-Agent: Mutt/1.9.4 (2018-02-28)
Subject: Re: [dpdk-dev] [PATCH] vhost: add doxygen comment to vDPA header
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.15
Precedence: list
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>
X-List-Received-Date: Thu, 11 Oct 2018 13:38:01 -0000

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