[3.13] gh-141004: Mark up docs of old PyMem macros (GH-143783) (GH-143865)

gh-141004: Mark up docs of old PyMem macros (GH-143783)

These had a docs-only deprecation notice since the first version of the docs in this repo. Nowadays we call things “soft deprecated” if there's just a note in the docs.

The deprecated directive needs a version, I went with the first one that had the notice (2.0; it's not in 1.6):
- https://docs.python.org/release/2.0/api/memoryInterface.html
- https://docs.python.org/release/1.6/api/memoryInterface.html

Since PEP 445, they are now direct aliases; there are no (additional) binary compatibility concerns over the preferred names.
(cherry picked from commit a009e78b79ec340d9ff0e1a8ad20f8178fd3257f)

Co-authored-by: Petr Viktorin <encukou@gmail.com>

diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst
index b93b3ebec73fbb47b71a4e2587121916c1462155..734b3298a8cd44d2eb8a08e7517846f852c6a4fb 100644 (file)
--- a/Doc/c-api/memory.rst
+++ b/Doc/c-api/memory.rst
@@ -294,17 +294,39 @@ The following type-oriented macros are provided for convenience.  Note  that
 
    Same as :c:func:`PyMem_Free`.
 
-In addition, the following macro sets are provided for calling the Python memory
-allocator directly, without involving the C API functions listed above. However,
-note that their use does not preserve binary compatibility across Python
-versions and is therefore deprecated in extension modules.
-
-* ``PyMem_MALLOC(size)``
-* ``PyMem_NEW(type, size)``
-* ``PyMem_REALLOC(ptr, size)``
-* ``PyMem_RESIZE(ptr, type, size)``
-* ``PyMem_FREE(ptr)``
-* ``PyMem_DEL(ptr)``
+
+Deprecated aliases
+------------------
+
+These are :term:`soft deprecated` aliases to existing functions and macros.
+They exist solely for backwards compatibility.
+
+.. list-table::
+   :widths: auto
+   :header-rows: 1
+
+   * * Deprecated alias
+     * Corresponding function or macro
+   * * .. c:macro:: PyMem_MALLOC(size)
+     * :c:func:`PyMem_Malloc`
+   * * .. c:macro:: PyMem_NEW(type, size)
+     * :c:macro:`PyMem_New`
+   * * .. c:macro:: PyMem_REALLOC(ptr, size)
+     * :c:func:`PyMem_Realloc`
+   * * .. c:macro:: PyMem_RESIZE(ptr, type, size)
+     * :c:macro:`PyMem_Resize`
+   * * .. c:macro:: PyMem_FREE(ptr)
+     * :c:func:`PyMem_Free`
+   * * .. c:macro:: PyMem_DEL(ptr)
+     * :c:func:`PyMem_Free`
+
+.. versionchanged:: 3.4
+
+   The macros are now aliases of the corresponding functions and macros.
+   Previously, their behavior was the same, but their use did not necessarily
+   preserve binary compatibility across Python versions.
+
+.. deprecated:: 2.0
 
 
 .. _objectinterface: