From a2392720d6108041d17960a86514ba859b436f05 Mon Sep 17 00:00:00 2001
From: Irit Katriel <1055913+iritkatriel@users.noreply.github.com>
Date: Wed, 21 Jun 2023 21:13:25 +0100
Subject: [PATCH] gh-84436: update docs on Py_None/Py_True/Py_False/Py_Ellipsis
 becoming immortal (#105195)

---
 Doc/c-api/bool.rst  | 25 ++++++++++++++-----------
 Doc/c-api/none.rst  | 10 +++++-----
 Doc/c-api/slice.rst |  9 ++++++---
 3 files changed, 25 insertions(+), 19 deletions(-)

diff --git a/Doc/c-api/bool.rst b/Doc/c-api/bool.rst
index c197d447e9618c..b2d8f2124fc203 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 b84a16a28ead56..1a497652ac5655 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 33169ccce89043..c54a659cf2ffd8 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.