doc: fix typos and errors in abi policy doc
PATCH 1/1 doc: fix typos and errors in abi policy doc
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.
--- doc/guides/contributing/abi_policy.rst | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-)
doc/guides/contributing/abi_policy.rst +10 -11
@@ -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@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@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.
Signature · 1 line
2.26.2
Gaetan,
Looks good, thank you for the tidy up.
Quoted 76 lines · Gaetan Rivet
Some errors in the document:
* API instead of ABI once.
Some typos:
*
__rte_depreciatedinstead 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 <[email protected]>cc Neil Horman <[email protected]>Signed-off-by Gaetan Rivet <[email protected]>--- doc/guides/contributing/abi_policy.rst | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-)doc/guides/contributing/abi_policy.rst +9
-10@@ -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@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@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:
doc/guides/contributing/abi_policy.rst Libraries · line 326
Quoted 7 lines
doc/guides/contributing/abi_policy.rst +1
-1@@ -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.
Thomas Monjalon
Applied14/05/2020 08:40, Ray Kinsella:
Quoted 18 lines · Gaetan Rivet
Quoted 17 lines
Some errors in the document:
* API instead of ABI once.
Some typos:
*
__rte_depreciatedinstead 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.
Quoted 8 lines
Quoted 6 lines
I'm not a native speaker though, so grain of salt applies.
Fixes fdf7471cccb8 ("doc: introduce major ABI versions")Cc Ray Kinsella <[email protected]>cc Neil Horman <[email protected]>Signed-off-by Gaetan Rivet <[email protected]>Acked-by Ray Kinsella <[email protected]>
Applied, thanks