[dpdk-dev] [PATCH v1] doc: fix typos and errors in abi policy doc

[dpdk-dev] [PATCH v1] doc: fix typos and errors in abi policy doc

[Gaetan Rivet]

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@ashroe.eu>
cc: Neil Horman <nhorman@tuxdriver.com>
Signed-off-by: Gaetan Rivet <grive@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@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.
-- 
2.26.2

Re: [dpdk-dev] [PATCH v1] doc: fix typos and errors in abi policy doc

[Ray Kinsella]

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@ashroe.eu>
> cc: Neil Horman <nhorman@tuxdriver.com>
> Signed-off-by: Gaetan Rivet <grive@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@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.
> 

Acked-by: Ray Kinsella <mdr@ashroe.eu>

Re: [dpdk-dev] [PATCH v1] doc: fix typos and errors in abi policy doc

[Thomas Monjalon]

14/05/2020 08:40, Ray Kinsella:
> 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@ashroe.eu>
> > cc: Neil Horman <nhorman@tuxdriver.com>
> > Signed-off-by: Gaetan Rivet <grive@u256.net>
> 
> Acked-by: Ray Kinsella <mdr@ashroe.eu>

Applied, thanks