gh-138098: Clarify strong references in `PyDict_Next` docs on the free-threaded build...

diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst
index e55c5c80cb83c0e0da58e70628d6d91c5e736ee8..0fbe26b56c0a7c6a19824d15efb41bda18da0f14 100644 (file)
--- a/Doc/c-api/dict.rst
+++ b/Doc/c-api/dict.rst
@@ -301,6 +301,15 @@ Dictionary Objects
       }
       Py_END_CRITICAL_SECTION();
 
+   .. note::
+
+      On the free-threaded build, this function can be used safely inside a
+      critical section. However, the references returned for *pkey* and *pvalue*
+      are :term:`borrowed <borrowed reference>` and are only valid while the
+      critical section is held. If you need to use these objects outside the
+      critical section or when the critical section can be suspended, create a
+      :term:`strong reference <strong reference>` (for example, using
+      :c:func:`Py_NewRef`).
 
 .. c:function:: int PyDict_Merge(PyObject *a, PyObject *b, int override)