gh-84436: update docs on Py_None/Py_True/Py_False/Py_Ellipsis becoming immortal (#105195)

3 files changed, 25 insertions, 19 deletions

diff --git a/Doc/c-api/bool.rst b/Doc/c-api/bool.rst
index c197d44..b2d8f21 100644
--- a/Doc/c-api/bool.rst
+++ b/Doc/c-api/bool.rst
@@ -6,7 +6,7 @@ Boolean Objects
 ---------------
 
 Booleans in Python are implemented as a subclass of integers.  There are only
-two booleans, :const:`Py_False` and :const:`Py_True`.  As such, the normal
+two booleans, :c:data:`Py_False` and :c:data:`Py_True`.  As such, the normal
 creation and deletion functions don't apply to booleans.  The following macros
 are available, however.
 
@@ -19,29 +19,32 @@ are available, however.
 
 .. c:var:: PyObject* Py_False
 
-   The Python ``False`` object.  This object has no methods.  It needs to be
-   treated just like any other object with respect to reference counts.
+   The Python ``False`` object.  This object has no methods and is
+   `immortal <https://peps.python.org/pep-0683/>`_.
+
+.. versionchanged:: 3.12
+   :c:data:`Py_False` is immortal.
 
 
 .. c:var:: PyObject* Py_True
 
-   The Python ``True`` object.  This object has no methods.  It needs to be treated
-   just like any other object with respect to reference counts.
+   The Python ``True`` object.  This object has no methods and is
+   `immortal <https://peps.python.org/pep-0683/>`_.
+
+.. versionchanged:: 3.12
+   :c:data:`Py_True` is immortal.
 
 
 .. c:macro:: Py_RETURN_FALSE
 
-   Return :const:`Py_False` from a function, properly incrementing its reference
-   count.
+   Return :c:data:`Py_False` from a function.
 
 
 .. c:macro:: Py_RETURN_TRUE
 
-   Return :const:`Py_True` from a function, properly incrementing its reference
-   count.
+   Return :c:data:`Py_True` from a function.
 
 
 .. c:function:: PyObject* PyBool_FromLong(long v)
 
-   Return a new reference to :const:`Py_True` or :const:`Py_False` depending on the
-   truth value of *v*.
+   Return :c:data:`Py_True` or :c:data:`Py_False`, depending on the truth value of *v*.
diff --git a/Doc/c-api/none.rst b/Doc/c-api/none.rst
index b84a16a..1a49765 100644
--- a/Doc/c-api/none.rst
+++ b/Doc/c-api/none.rst
@@ -15,12 +15,12 @@ same reason.
 
 .. c:var:: PyObject* Py_None
 
-   The Python ``None`` object, denoting lack of value.  This object has no methods.
-   It needs to be treated just like any other object with respect to reference
-   counts.
+   The Python ``None`` object, denoting lack of value.  This object has no methods
+   and is `immortal <https://peps.python.org/pep-0683/>`_.
 
+.. versionchanged:: 3.12
+   :c:data:`Py_None` is immortal.
 
 .. c:macro:: Py_RETURN_NONE
 
-   Properly handle returning :c:data:`Py_None` from within a C function (that is,
-   increment the reference count of ``None`` and return it.)
+   Return :c:data:`Py_None` from a function.
diff --git a/Doc/c-api/slice.rst b/Doc/c-api/slice.rst
index 33169cc..c54a659 100644
--- a/Doc/c-api/slice.rst
+++ b/Doc/c-api/slice.rst
@@ -118,6 +118,9 @@ Ellipsis Object
 
 .. c:var:: PyObject *Py_Ellipsis
 
-   The Python ``Ellipsis`` object.  This object has no methods.  It needs to be
-   treated just like any other object with respect to reference counts.  Like
-   :c:data:`Py_None` it is a singleton object.
+   The Python ``Ellipsis`` object.  This object has no methods.  Like
+   :c:data:`Py_None`, it is an `immortal <https://peps.python.org/pep-0683/>`_.
+   singleton object.
+
+   .. versionchanged:: 3.12
+      :c:data:`Py_Ellipsis` is immortal.