bpo-42294: Add borrowed/strong reference to doc glossary (GH-23206)

Add "borrowed reference" and "strong reference" to the documentation
glossary.

Enhance also Py_INCREF() and Py_NewRef() documentation.

1 files changed, 26 insertions, 9 deletions

diff --git a/Doc/c-api/refcounting.rst b/Doc/c-api/refcounting.rst
index b15c0e6..391907c 100644
--- a/Doc/c-api/refcounting.rst
+++ b/Doc/c-api/refcounting.rst
@@ -13,10 +13,14 @@ objects.
 
 .. c:function:: void Py_INCREF(PyObject *o)
 
-   Increment the reference count for object *o*.  The object must not be ``NULL``; if
-   you aren't sure that it isn't ``NULL``, use :c:func:`Py_XINCREF`.
+   Increment the reference count for object *o*.
 
-   See also :c:func:`Py_NewRef`.
+   This function is usually used to convert a :term:`borrowed reference` to a
+   :term:`strong reference` in-place. The :c:func:`Py_NewRef` function can be
+   used to create a new :term:`strong reference`.
+
+   The object must not be ``NULL``; if you aren't sure that it isn't
+   ``NULL``, use :c:func:`Py_XINCREF`.
 
 
 .. c:function:: void Py_XINCREF(PyObject *o)
@@ -29,9 +33,14 @@ objects.
 
 .. c:function:: PyObject* Py_NewRef(PyObject *o)
 
-   Increment the reference count of the object *o* and return the object *o*.
+   Create a new :term:`strong reference` to an object: increment the reference
+   count of the object *o* and return the object *o*.
+
+   When the :term:`strong reference` is no longer needed, :c:func:`Py_DECREF`
+   should be called on it to decrement the object reference count.
 
-   The object *o* must not be ``NULL``.
+   The object *o* must not be ``NULL``; use :c:func:`Py_XNewRef` if *o* can be
+   ``NULL``.
 
    For example::
 
@@ -42,6 +51,8 @@ objects.
 
        self->attr = Py_NewRef(obj);
 
+   See also :c:func:`Py_INCREF`.
+
    .. versionadded:: 3.10
 
 
@@ -56,10 +67,16 @@ objects.
 
 .. c:function:: void Py_DECREF(PyObject *o)
 
-   Decrement the reference count for object *o*.  The object must not be ``NULL``; if
-   you aren't sure that it isn't ``NULL``, use :c:func:`Py_XDECREF`.  If the reference
-   count reaches zero, the object's type's deallocation function (which must not be
-   ``NULL``) is invoked.
+   Decrement the reference count for object *o*.
+
+   If the reference count reaches zero, the object's type's deallocation
+   function (which must not be ``NULL``) is invoked.
+
+   This function is usually used to delete a :term:`strong reference` before
+   exiting its scope.
+
+   The object must not be ``NULL``; if you aren't sure that it isn't ``NULL``,
+   use :c:func:`Py_XDECREF`.
 
    .. warning::