From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Sun, 13 Jul 2025 06:52:58 +0000 (+0200)
Subject: [3.14] Docs: Fix and improve the `PyUnstable_Object_EnableDeferredRefcount` documenta... 
X-Git-Tag: v3.14.0rc1~84
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=a1ed132a19ac8a799d1c187527ce16e543e8146f;p=thirdparty%2FPython%2Fcpython.git

[3.14] Docs: Fix and improve the `PyUnstable_Object_EnableDeferredRefcount` documentation (GH-135323) (GH-136610)

Docs: Fix and improve the `PyUnstable_Object_EnableDeferredRefcount` documentation (GH-135323)
(cherry picked from commit 0d4fd10fbab2767fad3eb27639905c8885b88c89)

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
---

diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst
index 0fd159f1eb87..241fbd3a4866 100644
--- a/Doc/c-api/object.rst
+++ b/Doc/c-api/object.rst
@@ -596,12 +596,13 @@ Object Protocol
    if supported by the runtime.  In the :term:`free-threaded <free threading>` build,
    this allows the interpreter to avoid reference count adjustments to *obj*,
    which may improve multi-threaded performance.  The tradeoff is
-   that *obj* will only be deallocated by the tracing garbage collector.
+   that *obj* will only be deallocated by the tracing garbage collector, and
+   not when the interpreter no longer has any references to it.
 
-   This function returns ``1`` if deferred reference counting is enabled on *obj*
-   (including when it was enabled before the call),
+   This function returns ``1`` if deferred reference counting is enabled on *obj*,
    and ``0`` if deferred reference counting is not supported or if the hint was
-   ignored by the runtime. This function is thread-safe, and cannot fail.
+   ignored by the interpreter, such as when deferred reference counting is already
+   enabled on *obj*. This function is thread-safe, and cannot fail.
 
    This function does nothing on builds with the :term:`GIL` enabled, which do
    not support deferred reference counting. This also does nothing if *obj* is not
@@ -609,7 +610,8 @@ Object Protocol
    :c:func:`PyObject_GC_IsTracked`).
 
    This function is intended to be used soon after *obj* is created,
-   by the code that creates it.
+   by the code that creates it, such as in the object's :c:member:`~PyTypeObject.tp_new`
+   slot.
 
    .. versionadded:: 3.14