From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id 81036A034F; Wed, 13 May 2020 12:43:08 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 3EB371D523; Wed, 13 May 2020 12:43:08 +0200 (CEST) Received: from relay4-d.mail.gandi.net (relay4-d.mail.gandi.net [217.70.183.196]) by dpdk.org (Postfix) with ESMTP id 955791D524 for ; Wed, 13 May 2020 12:43:06 +0200 (CEST) X-Originating-IP: 86.246.31.132 Received: from inocybe.home (lfbn-idf2-1-566-132.w86-246.abo.wanadoo.fr [86.246.31.132]) (Authenticated sender: grive@u256.net) by relay4-d.mail.gandi.net (Postfix) with ESMTPSA id B7034E0011; Wed, 13 May 2020 10:43:05 +0000 (UTC) From: Gaetan Rivet To: dev@dpdk.org Cc: Ray Kinsella , Neil Horman Date: Wed, 13 May 2020 12:43:01 +0200 Message-Id: <20200513104301.46043-1-grive@u256.net> X-Mailer: git-send-email 2.26.2 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] [PATCH v1] doc: fix typos and errors in abi policy doc X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" 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 cc: Neil Horman Signed-off-by: Gaetan Rivet --- 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