From ddd30b2dd207c3c963874f0644cdff2ee5989575 Mon Sep 17 00:00:00 2001
From: Petr Viktorin <encukou@gmail.com>
Date: Fri, 14 May 2021 07:22:44 +0200
Subject: [PATCH] Reword paragraph on specific value for Py_LIMITED_API
 (GH-26101)

---
 Doc/c-api/stable.rst | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/Doc/c-api/stable.rst b/Doc/c-api/stable.rst
index 2f67b097eae..4ae20e93e36 100644
--- a/Doc/c-api/stable.rst
+++ b/Doc/c-api/stable.rst
@@ -41,22 +41,22 @@ embedding Python.)
 
 .. c:macro:: Py_LIMITED_API
 
-   Define this macro ``Py_LIMITED_API`` before including ``Python.h`` to
-   opt in to only use the Limited API.
+   Define this macro before including ``Python.h`` to opt in to only use
+   the Limited API, and to select the Limited API version.
 
-   Defining ``Py_LIMITED_API`` to ``3`` will limit the available API so that
-   the extension will work without recompilation with all Python 3.x releases
-   (x>=2) on the particular  :ref:`platform <stable-abi-platform>`.
+   Define ``Py_LIMITED_API`` to the value of :c:data:`PY_VERSION_HEX`
+   corresponding to the lowest Python version your extension supports.
+   The extension will work without recompilation with all Python 3 releases
+   from the specified one onward, and can use Limited API introduced up to that
+   version.
 
-   Defining ``Py_LIMITED_API`` to a value of :c:data:`PY_VERSION_HEX` will
-   limit the available API so that the extension will work without
-   recompilation with all Python 3 releases from the specified one.
-   This will allow using additional API introduced up to this version,
-   but the extension will lose compatibility with earlier Python versions.
    Rather than using the ``PY_VERSION_HEX`` macro directly, hardcode a minimum
    minor version (e.g. ``0x030A0000`` for Python 3.10) for stability when
    compiling with future Python versions.
 
+   You can also define ``Py_LIMITED_API`` to ``3``. This works the same as
+   ``0x03020000`` (Python 3.2, the version that introduced Limited API).
+
 On Windows, extensions that use the Stable ABI should be linked against
 ``python3.dll`` rather than a version-specific library such as
 ``python39.dll``.