[dpdk-dev] [PATCH v1] doc: fix typos and errors in abi policy doc
Ray Kinsella
mdr at ashroe.eu
Thu May 14 08:40:21 CEST 2020
CC: John + Marko
Gaetan,
Looks good, thank you for the tidy up.
On 13/05/2020 11:43, Gaetan Rivet wrote:
> Some errors in the document:
>
> * API instead of ABI once.
>
> Some typos:
>
> * __rte_depreciated instead of __rte_deprecated.
> * missing ```` around value.
> * inconsistent reference to major ABI version, most
> of the time described without the minor appended, except once.
>
> Verbosity and grammar:
>
> * Long sentences that would be better cut short.
> * Comma abuse.
> * 'May' used where 'can' seems more fitting.
>
> I'm not a native speaker though, so grain of salt applies.
>
> Fixes: fdf7471cccb8 ("doc: introduce major ABI versions")
> Cc: Ray Kinsella <mdr at ashroe.eu>
> cc: Neil Horman <nhorman at tuxdriver.com>
> Signed-off-by: Gaetan Rivet <grive at u256.net>
> ---
> doc/guides/contributing/abi_policy.rst | 21 ++++++++++-----------
> 1 file changed, 10 insertions(+), 11 deletions(-)
>
> diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
> index 05ca95980..2198519d9 100644
> --- a/doc/guides/contributing/abi_policy.rst
> +++ b/doc/guides/contributing/abi_policy.rst
> @@ -220,19 +220,18 @@ Examples of ABI Changes
> The following are examples of allowable ABI changes occurring between
> declarations of major ABI versions.
>
> -* DPDK 19.11 release, defines the function ``rte_foo()``, and ``rte_foo()``
> - as part of the major ABI version ``20``.
> +* DPDK 19.11 release defines the function ``rte_foo()`` ; ``rte_foo()``
> + is part of the major ABI version ``20``.
>
> -* DPDK 20.02 release defines a new function ``rte_foo(uint8_t bar)``, and
> - this is not a problem as long as the symbol ``rte_foo at DPDK20`` is
> +* DPDK 20.02 release defines a new function ``rte_foo(uint8_t bar)``.
> + This is not a problem as long as the symbol ``rte_foo at DPDK20`` is
> preserved through :ref:`abi_versioning`.
>
> - The new function may be marked with the ``__rte_experimental`` tag for a
> number of releases, as described in the section :ref:`experimental_apis`.
>
> - - Once ``rte_foo(uint8_t bar)`` becomes non-experimental ``rte_foo()`` is then
> - declared as ``__rte_depreciated``, with an associated deprecation notice
> - provided.
> + - Once ``rte_foo(uint8_t bar)`` becomes non-experimental, ``rte_foo()`` is
> + declared as ``__rte_deprecated`` and an deprecation notice is provided.
>
> * DPDK 19.11 is not re-released to include ``rte_foo(uint8_t bar)``, the new
> version of ``rte_foo`` only exists from DPDK 20.02 onwards as described in the
> @@ -242,13 +241,13 @@ declarations of major ABI versions.
> rte_baz()``. This function may or may not exist in the DPDK 20.05 release.
>
> * An application ``dPacket`` wishes to use ``rte_foo(uint8_t bar)``, before the
> - declaration of the DPDK ``21`` major API version. The application can only
> + declaration of the DPDK ``21`` major ABI version. The application can only
> ensure its runtime dependencies are met by specifying ``DPDK (>= 20.2)`` as
> - an explicit package dependency, as the soname only may only indicate the
> + an explicit package dependency, as the soname can only indicate the
> supported major ABI version.
>
> * At the release of DPDK 20.11, the function ``rte_foo(uint8_t bar)`` becomes
> - formally part of then new major ABI version DPDK 21.0 and ``rte_foo()`` may be
> + formally part of then new major ABI version DPDK ``21`` and ``rte_foo()`` may be
> removed.
>
> .. _deprecation_notices:
> @@ -322,6 +321,6 @@ Libraries
>
> Libraries marked as ``experimental`` are entirely not considered part of an ABI
> version, and may change without warning at any time. Experimental libraries
> -always have a major version of ``0`` to indicate they exist outside of
> +always have a major ABI version of ``0`` to indicate they exist outside of
> :ref:`abi_versioning` , with the minor version incremented with each ABI change
> to library.
>
Acked-by: Ray Kinsella <mdr at ashroe.eu>
More information about the dev
mailing list