[3.14] gh-141004: Document `Py_LOCAL` and `Py_LOCAL_INLINE` (GH-141725) (GH-141761)

gh-141004: Document `Py_LOCAL` and `Py_LOCAL_INLINE` (GH-141725)
(cherry picked from commit 3149d64c93f02217eb01c0fd82c26a685b5281c1)

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index 37c1649124ea9c3aa2d56d51b4387c195a3b7e51..58409590c93b0a3ec439f3eaa43ccb5826bd2ce0 100644 (file)
--- a/Doc/c-api/intro.rst
+++ b/Doc/c-api/intro.rst
@@ -171,6 +171,17 @@ complete listing.
    Like ``getenv(s)``, but returns ``NULL`` if :option:`-E` was passed on the
    command line (see :c:member:`PyConfig.use_environment`).
 
+.. c:macro:: Py_LOCAL(type)
+
+   Declare a function returning the specified *type* using a fast-calling
+   qualifier for functions that are local to the current file.
+   Semantically, this is equivalent to ``static type``.
+
+.. c:macro:: Py_LOCAL_INLINE(type)
+
+   Equivalent to :c:macro:`Py_LOCAL` but additionally requests the function
+   be inlined.
+
 .. c:macro:: Py_MAX(x, y)
 
    Return the maximum value between ``x`` and ``y``.

diff --git a/Doc/whatsnew/2.5.rst b/Doc/whatsnew/2.5.rst
index 3430ac8668e280c85215b0db6d311a6b38b8c5e9..e195d9d462dda9d8ddcfd9cc951c57e2ef52172e 100644 (file)
--- a/Doc/whatsnew/2.5.rst
+++ b/Doc/whatsnew/2.5.rst
@@ -2169,9 +2169,9 @@ Changes to Python's build process and to the C API include:
 
 * Two new macros can be used to indicate C functions that are local to the
   current file so that a faster calling convention can be used.
-  ``Py_LOCAL(type)`` declares the function as returning a value of the
+  :c:macro:`Py_LOCAL` declares the function as returning a value of the
   specified *type* and uses a fast-calling qualifier.
-  ``Py_LOCAL_INLINE(type)`` does the same thing and also requests the
+  :c:macro:`Py_LOCAL_INLINE` does the same thing and also requests the
   function be inlined.  If macro :c:macro:`!PY_LOCAL_AGGRESSIVE` is defined before
   :file:`python.h` is included, a set of more aggressive optimizations are enabled
   for the module; you should benchmark the results to find out if these