> -----Original Message----- > From: Neil Horman [mailto:nhor...@tuxdriver.com] > Sent: Monday, January 22, 2018 1:48 AM > To: dev@dpdk.org > Cc: Neil Horman <nhor...@tuxdriver.com>; Thomas Monjalon > <tho...@monjalon.net>; Mcnamara, John <john.mcnam...@intel.com>; > Richardson, Bruce <bruce.richard...@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 <nhor...@tuxdriver.com> > CC: Thomas Monjalon <tho...@monjalon.net> > CC: "Mcnamara, John" <john.mcnam...@intel.com> > CC: Bruce Richardson <bruce.richard...@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. Acked-by: John McNamara <john.mcnam...@intel.com>
