[dpdk-dev] [PATCHv4 5/5] doc: Add ABI __experimental tag documentation
Neil Horman
nhorman at tuxdriver.com
Thu Jan 11 22:29:31 CET 2018
On Thu, Jan 11, 2018 at 08:06:48PM +0000, Ferruh Yigit wrote:
> On 12/13/2017 3:17 PM, Neil Horman wrote:
> > 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>
> > ---
> > doc/guides/contributing/versioning.rst | 9 +++++++++
> > 1 file changed, 9 insertions(+)
> >
> > diff --git a/doc/guides/contributing/versioning.rst b/doc/guides/contributing/versioning.rst
> > index 400090628..53f56397e 100644
> > --- a/doc/guides/contributing/versioning.rst
> > +++ b/doc/guides/contributing/versioning.rst
> > @@ -50,6 +50,15 @@ those new APIs and start finding issues with them, new DPDK APIs will be
> > automatically marked as ``experimental`` to allow for a period of stabilization
> > before they become part of a tracked ABI.
> >
> > +Note that marking an API as experimental is a two 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 __experimental tag (see rte_compat.h). The DPDK build makefiles
> > +preform a check to ensure that the map file and the C code reflect the same
> > +list of symbols.
>
> There are more steps we historically do to mark an API as experimental:
> - Add to function header comment experimental for API documentation, preferably
> with a warning tag to highlight it:
>
> /**
> * @warning
> * @b EXPERIMENTAL:
> ....
> */
>
> - If whole APIs in header file are experimental, add same experimental warning
> doxygen comment in file comment, again preferably with warning.
>
> - If whole library is experimental, put EXPERIMENTAL tag into maintainers file
> as well.
>
Is that documented somewhere? I'd like to add this to the same location that it
otherwise is written out. The above location was the only place in the guide
that I could find reference to experimental markings.
> > +
> > 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
> >
>
>
More information about the dev
mailing list