Rewrite documentation according to review in python#106522.

Doc/c-api/mapping.rst

@@ -35,26 +35,30 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
 
 .. c:function:: int PyMapping_GetOptionalItem(PyObject *obj, PyObject *key, PyObject **result)
 
-   Variant of :c:func:`PyObject_GetItem` which doesn't raise :exc:`KeyError`.
+   Variant of :c:func:`PyObject_GetItem` which doesn't raise
+   :exc:`KeyError` if the key is not found.
 
-   Return ``1`` and set ``*result != NULL`` if the key is found.
-   Return ``0`` and set ``*result == NULL`` if the key is not found;
+   If the key is found, return ``1`` and set *\*result* to a new
+   :term:`strong reference` to the corresponding value.
+   If the key is not found, return ``0`` and set *\*result* to ``NULL``;
    the :exc:`KeyError` is silenced.
-   Return ``-1`` and set ``*result == NULL`` if an error other than
-   :exc:`KeyError` is raised.
+   If an error other than :exc:`KeyError` is raised, return ``-1`` and
+   set *\*result* to ``NULL``.
 
    .. versionadded:: 3.13
 
 
 .. c:function:: int PyMapping_GetOptionalItemString(PyObject *obj, const char *key, PyObject **result)
 
-   Variant of :c:func:`PyMapping_GetItemString` which doesn't raise :exc:`KeyError`.
+   Variant of :c:func:`PyMapping_GetItemString` which doesn't raise
+   :exc:`KeyError` if the key is not found.
 
-   Return ``1`` and set ``*result != NULL`` if the key is found.
-   Return ``0`` and set ``*result == NULL`` if the key is not found;
+   If the key is found, return ``1`` and set *\*result* to a new
+   :term:`strong reference` to the corresponding value.
+   If the key is not found, return ``0`` and set *\*result* to ``NULL``;
    the :exc:`KeyError` is silenced.
-   Return ``-1`` and set ``*result == NULL`` if an error other than
-   :exc:`KeyError` is raised.
+   If an error other than :exc:`KeyError` is raised, return ``-1`` and
+   set *\*result* to ``NULL``.
 
    .. versionadded:: 3.13
 

Doc/whatsnew/3.13.rst

@@ -737,7 +737,7 @@ New Features
 * Add :c:func:`PyMapping_GetOptionalItem` and
   :c:func:`PyMapping_GetOptionalItemString`: variants of
   :c:func:`PyObject_GetAttr` and :c:func:`PyMapping_GetItemString` which don't
-  raise :exc:`KeyError`.
+  raise :exc:`KeyError` if the key is not found.
   These variants are more convenient and faster if the missing key should not
   be treated as a failure.
   (Contributed by Serhiy Storchaka in :gh:`106307`.)

Include/abstract.h

@@ -811,13 +811,14 @@ PyAPI_FUNC(PyObject *) PyMapping_GetItemString(PyObject *o,
                                                const char *key);
 
 /* Variants of PyObject_GetItem() and PyMapping_GetItemString() which don't
-   raise KeyError.
+   raise KeyError if the key is not found.
 
-   Return 1 and set *result != NULL if the key is found.
-   Return 0 and set *result == NULL if the key is not found;
+   If the key is found, return 1 and set *result to a new strong
+   reference to the corresponding value.
+   If the key is not found, return 0 and set *result to NULL;
    the KeyError is silenced.
-   Return -1 and set *result == NULL if an error other than KeyError
-   is raised.
+   If an error other than KeyError is raised, return -1 and
+   set *result to NULL.
 */
 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030d0000
 PyAPI_FUNC(int) PyMapping_GetOptionalItem(PyObject *, PyObject *, PyObject **);