[3.12] Improve some C API documentation (GH-108768) (#108785)

* Express functions which take argument as a C string in terms of
  functions which take Python object.
* Use "note" directive for PyMapping_HasKey() and
  PyMapping_HasKeyString() notes..
(cherry picked from commit 6f97eeec222f81bd7ae836c149872a40b079e2a6)

3 files changed, 43 insertions, 44 deletions

diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst
index f668f84..5ccbfe6 100644
--- a/Doc/c-api/dict.rst
+++ b/Doc/c-api/dict.rst
@@ -70,12 +70,9 @@ Dictionary Objects
 
 .. c:function:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
 
-   .. index:: single: PyUnicode_FromString()
-
-   Insert *val* into the dictionary *p* using *key* as a key. *key* should
-   be a :c:expr:`const char*` UTF-8 encoded bytes string.  The key object is created using
-   ``PyUnicode_FromString(key)``.  Return ``0`` on success or ``-1`` on
-   failure.  This function *does not* steal a reference to *val*.
+   This is the same as :c:func:`PyDict_SetItem`, but *key* is
+   specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
+   rather than a :c:expr:`PyObject*`.
 
 
 .. c:function:: int PyDict_DelItem(PyObject *p, PyObject *key)
@@ -88,10 +85,9 @@ Dictionary Objects
 
 .. c:function:: int PyDict_DelItemString(PyObject *p, const char *key)
 
-   Remove the entry in dictionary *p* which has a key specified by the UTF-8
-   encoded bytes string *key*.
-   If *key* is not in the dictionary, :exc:`KeyError` is raised.
-   Return ``0`` on success or ``-1`` on failure.
+   This is the same as :c:func:`PyDict_DelItem`, but *key* is
+   specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
+   rather than a :c:expr:`PyObject*`.
 
 
 .. c:function:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
diff --git a/Doc/c-api/mapping.rst b/Doc/c-api/mapping.rst
index d94a9dc..0c42b91 100644
--- a/Doc/c-api/mapping.rst
+++ b/Doc/c-api/mapping.rst
@@ -28,30 +28,28 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
 
 .. c:function:: PyObject* PyMapping_GetItemString(PyObject *o, const char *key)
 
-   Return element of *o* corresponding to the string *key* or ``NULL`` on failure.
-   This is the equivalent of the Python expression ``o[key]``.
-   See also :c:func:`PyObject_GetItem`.
+   This is the same as :c:func:`PyObject_GetItem`, but *key* is
+   specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
+   rather than a :c:expr:`PyObject*`.
 
 
 .. c:function:: int PyMapping_SetItemString(PyObject *o, const char *key, PyObject *v)
 
-   Map the string *key* to the value *v* in object *o*.  Returns ``-1`` on
-   failure.  This is the equivalent of the Python statement ``o[key] = v``.
-   See also :c:func:`PyObject_SetItem`.  This function *does not* steal a
-   reference to *v*.
+   This is the same as :c:func:`PyObject_SetItem`, but *key* is
+   specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
+   rather than a :c:expr:`PyObject*`.
 
 
 .. c:function:: int PyMapping_DelItem(PyObject *o, PyObject *key)
 
-   Remove the mapping for the object *key* from the object *o*.  Return ``-1``
-   on failure.  This is equivalent to the Python statement ``del o[key]``.
    This is an alias of :c:func:`PyObject_DelItem`.
 
 
 .. c:function:: int PyMapping_DelItemString(PyObject *o, const char *key)
 
-   Remove the mapping for the string *key* from the object *o*.  Return ``-1``
-   on failure.  This is equivalent to the Python statement ``del o[key]``.
+   This is the same as :c:func:`PyObject_DelItem`, but *key* is
+   specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
+   rather than a :c:expr:`PyObject*`.
 
 
 .. c:function:: int PyMapping_HasKey(PyObject *o, PyObject *key)
@@ -60,20 +58,25 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
    This is equivalent to the Python expression ``key in o``.
    This function always succeeds.
 
-   Note that exceptions which occur while calling the :meth:`~object.__getitem__`
-   method will get suppressed.
-   To get error reporting use :c:func:`PyObject_GetItem()` instead.
+   .. note::
+
+      Exceptions which occur when this calls :meth:`~object.__getitem__`
+      method are silently ignored.
+      For proper error handling, use :c:func:`PyObject_GetItem()` instead.
 
 
 .. c:function:: int PyMapping_HasKeyString(PyObject *o, const char *key)
 
-   Return ``1`` if the mapping object has the key *key* and ``0`` otherwise.
-   This is equivalent to the Python expression ``key in o``.
-   This function always succeeds.
+   This is the same as :c:func:`PyMapping_HasKey`, but *key* is
+   specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
+   rather than a :c:expr:`PyObject*`.
+
+   .. note::
 
-   Note that exceptions which occur while calling the :meth:`~object.__getitem__`
-   method and creating a temporary string object will get suppressed.
-   To get error reporting use :c:func:`PyMapping_GetItemString()` instead.
+      Exceptions that occur when this calls :meth:`~object.__getitem__`
+      method or while creating the temporary :class:`str`
+      object are silently ignored.
+      For proper error handling, use :c:func:`PyMapping_GetItemString` instead.
 
 
 .. c:function:: PyObject* PyMapping_Keys(PyObject *o)
diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst
index 4a3fed1..d88de79 100644
--- a/Doc/c-api/object.rst
+++ b/Doc/c-api/object.rst
@@ -42,15 +42,15 @@ Object Protocol
 
 .. c:function:: int PyObject_HasAttrString(PyObject *o, const char *attr_name)
 
-   Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise.  This
-   is equivalent to the Python expression ``hasattr(o, attr_name)``.  This function
-   always succeeds.
+   This is the same as :c:func:`PyObject_HasAttr`, but *attr_name* is
+   specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
+   rather than a :c:expr:`PyObject*`.
 
    .. note::
 
       Exceptions that occur when this calls :meth:`~object.__getattr__` and
-      :meth:`~object.__getattribute__` methods or while creating the temporary :class:`str`
-      object are silently ignored.
+      :meth:`~object.__getattribute__` methods or while creating the temporary
+      :class:`str` object are silently ignored.
       For proper error handling, use :c:func:`PyObject_GetAttrString` instead.
 
 
@@ -63,9 +63,9 @@ Object Protocol
 
 .. c:function:: PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name)
 
-   Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
-   value on success, or ``NULL`` on failure. This is the equivalent of the Python
-   expression ``o.attr_name``.
+   This is the same as :c:func:`PyObject_GetAttr`, but *attr_name* is
+   specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
+   rather than a :c:expr:`PyObject*`.
 
 
 .. c:function:: PyObject* PyObject_GenericGetAttr(PyObject *o, PyObject *name)
@@ -92,10 +92,9 @@ Object Protocol
 
 .. c:function:: int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)
 
-   Set the value of the attribute named *attr_name*, for object *o*, to the value
-   *v*. Raise an exception and return ``-1`` on failure;
-   return ``0`` on success.  This is the equivalent of the Python statement
-   ``o.attr_name = v``.
+   This is the same as :c:func:`PyObject_SetAttr`, but *attr_name* is
+   specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
+   rather than a :c:expr:`PyObject*`.
 
    If *v* is ``NULL``, the attribute is deleted, but this feature is
    deprecated in favour of using :c:func:`PyObject_DelAttrString`.
@@ -121,8 +120,9 @@ Object Protocol
 
 .. c:function:: int PyObject_DelAttrString(PyObject *o, const char *attr_name)
 
-   Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
-   This is the equivalent of the Python statement ``del o.attr_name``.
+   This is the same as :c:func:`PyObject_DelAttr`, but *attr_name* is
+   specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
+   rather than a :c:expr:`PyObject*`.
 
 
 .. c:function:: PyObject* PyObject_GenericGetDict(PyObject *o, void *context)