[dpdk-dev] [[PATCH v5] 5/5] doc: Add ABI __experimental tag documentation

Thomas Monjalon thomas at monjalon.net
Mon Jan 29 22:42:24 CET 2018


23/01/2018 11:35, Mcnamara, John:
> 
> > -----Original Message-----
> > From: Neil Horman [mailto:nhorman at tuxdriver.com]
> > Sent: Monday, January 22, 2018 1:48 AM
> > To: dev at dpdk.org
> > Cc: Neil Horman <nhorman at tuxdriver.com>; Thomas Monjalon
> > <thomas at monjalon.net>; Mcnamara, John <john.mcnamara at intel.com>;
> > Richardson, Bruce <bruce.richardson at intel.com>
> > 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 <nhorman at tuxdriver.com>
> > CC: Thomas Monjalon <thomas at monjalon.net>
> > CC: "Mcnamara, John" <john.mcnamara at intel.com>
> > CC: Bruce Richardson <bruce.richardson at intel.com>
> > ...
> > +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.


More information about the dev mailing list