#8578: mention danger of not incref'ing weak referenced object.

diff --git a/Doc/c-api/weakref.rst b/Doc/c-api/weakref.rst
index 081419dcb4c22b68c35198c9a8e79f1f75f5a56c..8a36110386afcee45c8b0d7813900f4e539da572 100644 (file)
--- a/Doc/c-api/weakref.rst
+++ b/Doc/c-api/weakref.rst
@@ -53,7 +53,14 @@ as much as it can.
 .. cfunction:: PyObject* PyWeakref_GetObject(PyObject *ref)
 
    Return the referenced object from a weak reference, *ref*.  If the referent is
-   no longer live, returns ``None``.
+   no longer live, returns :const:`Py_None`.
+
+   .. warning::
+
+      This function returns a **borrowed reference** to the referenced object.
+      This means that you should always call :cfunc:`Py_INCREF` on the object
+      except if you know that it cannot be destroyed while you are still
+      using it.
 
 
 .. cfunction:: PyObject* PyWeakref_GET_OBJECT(PyObject *ref)