> -----Original Message----- > From: Neil Horman [mailto:[email protected]] > Sent: Monday, January 22, 2018 1:48 AM > To: [email protected] > Cc: Neil Horman <[email protected]>; Thomas Monjalon > <[email protected]>; Mcnamara, John <[email protected]>; > Richardson, Bruce <[email protected]> > 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 <[email protected]> > CC: Thomas Monjalon <[email protected]> > CC: "Mcnamara, John" <[email protected]> > CC: Bruce Richardson <[email protected]> > ... > +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 <[email protected]>
