From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from out3-smtp.messagingengine.com (out3-smtp.messagingengine.com [66.111.4.27]) by dpdk.org (Postfix) with ESMTP id 8B4801B379 for ; Mon, 29 Jan 2018 22:43:11 +0100 (CET) Received: from compute1.internal (compute1.nyi.internal [10.202.2.41]) by mailout.nyi.internal (Postfix) with ESMTP id 040EA210A1; Mon, 29 Jan 2018 16:43:11 -0500 (EST) Received: from frontend1 ([10.202.2.160]) by compute1.internal (MEProxy); Mon, 29 Jan 2018 16:43:11 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=monjalon.net; h= cc:content-transfer-encoding:content-type:date:from:in-reply-to :message-id:mime-version:references:subject:to:x-me-sender :x-me-sender:x-sasl-enc; s=mesmtp; bh=zOpD130gkNhpYhfiTKWuWH/CIK eNZ0iWxfDdv6KKMXk=; b=Fyj8EofGttsgYw6H/UMTq5Uq702SGTtQj36Wo2YkM9 1qtnX8hreKJ8Jv3pJii71o98RwgTvooTTufLvr44rx5rs7lF9GdNdLZ37fG1RJ1Q UcL7tOvIbR8pKWDdZ1ku46ECWh7WYi5GfPw3NkP/y7NDphRuSZLyP7TacWwt/o8H s= DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-transfer-encoding:content-type :date:from:in-reply-to:message-id:mime-version:references :subject:to:x-me-sender:x-me-sender:x-sasl-enc; s=fm1; bh=zOpD13 0gkNhpYhfiTKWuWH/CIKeNZ0iWxfDdv6KKMXk=; b=UPdhOWOPZlKMTmLQsREDeL U6yYMS3HaenDJAKFWy5XzUpwnUiaGmEUIRspv2r3zSvf9E1Wcp4H8MqGK+k+5sBd b8zlZ74Ikg3OLa34kST3QC95PzqX75zn1KpkyHd1xuk8gm3yl0up0IyQ0zBBd5AE XAqtPONKnWK5W1XN47htciO6GEF7hzlR63+3iP7Z2kalOME3LyzqXbpvmmKSXmke Kz4l7gP/6CyMenmW3nwDq8gEAO8uPzBHFApALUUmWH1tWVaLXj89DRs3q1e/KDtA ODrVOmXLBYyPvgxHbXGqBShritMdDpU5hnRglRyyfB20c/RbO+56bZTRTgISkN9w == X-ME-Sender: Received: from xps.localnet (184.203.134.77.rev.sfr.net [77.134.203.184]) by mail.messagingengine.com (Postfix) with ESMTPA id 9CAFF7E3D5; Mon, 29 Jan 2018 16:43:10 -0500 (EST) From: Thomas Monjalon To: Neil Horman Cc: dev@dpdk.org, "Mcnamara, John" , "Richardson, Bruce" Date: Mon, 29 Jan 2018 22:42:24 +0100 Message-ID: <2651138.J81ghoYPcA@xps> In-Reply-To: References: <20171201185628.16261-1-nhorman@tuxdriver.com> <20180122014807.24654-6-nhorman@tuxdriver.com> MIME-Version: 1.0 Content-Transfer-Encoding: 7Bit Content-Type: text/plain; charset="us-ascii" Subject: Re: [dpdk-dev] [[PATCH v5] 5/5] doc: Add ABI __experimental tag documentation X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 29 Jan 2018 21:43:11 -0000 23/01/2018 11:35, Mcnamara, John: > > > -----Original Message----- > > From: Neil Horman [mailto:nhorman@tuxdriver.com] > > Sent: Monday, January 22, 2018 1:48 AM > > To: dev@dpdk.org > > Cc: Neil Horman ; Thomas Monjalon > > ; Mcnamara, John ; > > Richardson, Bruce > > Subject: [[PATCH v5] 5/5] doc: Add ABI __experimental tag documentation > > > > Document the need to add the __experimental tag to appropriate functions > > > > Signed-off-by: Neil Horman > > CC: Thomas Monjalon > > CC: "Mcnamara, John" > > CC: Bruce Richardson > > ... > > +Note that marking an API as experimental is a multi step process. To > > +mark an API as experimental, the symbols which are desired to be > > +exported must be placed in an EXPERIMENTAL version block in the > > +corresponding libraries' version map script. Secondly, the > > +corresponding definitions of those exported functions, and their > > +forward declarations (in the development header files), must be marked > > +with the __rte_experimental tag (see rte_compat.h). The DPDK build > > +makefiles perform a check to ensure that the map file and the C code > > +reflect the same list of symbols. This check can be circumvented by > > defining ALLOW_EXPERIMENTAL_API during compilation in the corresponding > > library Makefile. > > + > > +In addition to tagging the code with __rte_experimental, the doxygen > > +markup must also contain the EXPERIMENTAL string, and the MAINTAINER > > +file should note that the library contains EXPERIMENTAL APIs. > > + > > ABI versions, once released, are available until such time as their > > deprecation has been noted in the Release Notes for at least one major > > release cycle. For example consider the case where the ABI for DPDK 2.0 > > has been > > -- > > 2.14.3 > > Thanks for the update, and this work in general. > > The rendered docs would probably look a better better with __rte_experimental > and ALLOW_EXPERIMENTAL_API is fixed width backticks ``var`` but that is only > a "nice to have" so no need for a respin. Backticks added on apply. Also changed the last sentence from the MAINTAINER file should note that the library contains EXPERIMENTAL APIs. to the MAINTAINERS file should note the EXPERIMENTAL libraries. Indeed, the practice is to note only new libraries as experimental in the MAINTAINERS files.