bpo-39153: Clarify C API *SetItem refcounting semantics (GH-18220)
Some of the *SetItem methods in the C API steal a reference to the
given value. This annotates the better behaved ones to assure the
reader that these are not the ones with the inconsistent behaviour.
* 📜🤖 Added by blurb_it.
* make docs consistent with signature
Co-authored-by: blurb-it[bot] <43283697+blurb-it[bot]@users.noreply.github.com>
diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst
index e7922dc..e48c11d 100644
--- a/Doc/c-api/dict.rst
+++ b/Doc/c-api/dict.rst
@@ -62,19 +62,20 @@
.. c:function:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
- Insert *value* into the dictionary *p* with a key of *key*. *key* must be
+ Insert *val* into the dictionary *p* with a key of *key*. *key* must be
:term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return
- ``0`` on success or ``-1`` on failure.
+ ``0`` on success or ``-1`` on failure. This function *does not* steal a
+ reference to *val*.
.. c:function:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
.. index:: single: PyUnicode_FromString()
- Insert *value* into the dictionary *p* using *key* as a key. *key* should
+ Insert *val* into the dictionary *p* using *key* as a key. *key* should
be a :c:type:`const char\*`. The key object is created using
``PyUnicode_FromString(key)``. Return ``0`` on success or ``-1`` on
- failure.
+ failure. This function *does not* steal a reference to *val*.
.. c:function:: int PyDict_DelItem(PyObject *p, PyObject *key)