[3.9] More minor fixes to C API docs (GH-31525) (GH-32259)

* wording fixes in type.rst

* grammar and punctuation in sys.rst

* set: grammar fixes

* structures: capitalization fix

* grammar fixes for sequence

* objects: point to Py_TYPE instead of direct object access

* numbers: add more explicit Python equivalences

* method: add missing period

* memory: grammar fix

* mapping: grammar fixes

* long: grammar fix

* iter: fix grammar for PyAIter_Check

* init: grammar fix.
(cherry picked from commit 897bc6f)

Co-authored-by: Jelle Zijlstra <[email protected]>

Author: JelleZijlstra

Doc/c-api/init.rst

@@ -1688,7 +1688,7 @@ is not possible due to its implementation being opaque at build time.
    argument is `NULL`.
 
    .. note::
-      A freed key becomes a dangling pointer, you should reset the key to
+      A freed key becomes a dangling pointer. You should reset the key to
       `NULL`.
 
 

Doc/c-api/long.rst

@@ -41,7 +41,7 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    Return a new :c:type:`PyLongObject` object from *v*, or ``NULL`` on failure.
 
    The current implementation keeps an array of integer objects for all integers
-   between ``-5`` and ``256``, when you create an int in that range you actually
+   between ``-5`` and ``256``. When you create an int in that range you actually
    just get back a reference to the existing object.
 
 

Doc/c-api/mapping.rst

@@ -11,10 +11,10 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
 
 .. c:function:: int PyMapping_Check(PyObject *o)
 
-   Return ``1`` if the object provides mapping protocol or supports slicing,
+   Return ``1`` if the object provides the mapping protocol or supports slicing,
    and ``0`` otherwise.  Note that it returns ``1`` for Python classes with
-   a :meth:`__getitem__` method since in general case it is impossible to
-   determine what type of keys it supports. This function always succeeds.
+   a :meth:`__getitem__` method, since in general it is impossible to
+   determine what type of keys the class supports. This function always succeeds.
 
 
 .. c:function:: Py_ssize_t PyMapping_Size(PyObject *o)

Doc/c-api/method.rst

@@ -27,7 +27,7 @@ to bind a :c:data:`PyCFunction` to a class object. It replaces the former call
 
 .. c:function:: PyObject* PyInstanceMethod_New(PyObject *func)
 
-   Return a new instance method object, with *func* being any callable object
+   Return a new instance method object, with *func* being any callable object.
    *func* is the function that will be called when the instance method is
    called.
 

Doc/c-api/number.rst

@@ -44,7 +44,7 @@ Number Protocol
 .. c:function:: PyObject* PyNumber_FloorDivide(PyObject *o1, PyObject *o2)
 
    Return the floor of *o1* divided by *o2*, or ``NULL`` on failure.  This is
-   equivalent to the "classic" division of integers.
+   the equivalent of the Python expression ``o1 // o2``.
 
 
 .. c:function:: PyObject* PyNumber_TrueDivide(PyObject *o1, PyObject *o2)
@@ -53,7 +53,7 @@ Number Protocol
    *o2*, or ``NULL`` on failure.  The return value is "approximate" because binary
    floating point numbers are approximate; it is not possible to represent all real
    numbers in base two.  This function can return a floating point value when
-   passed two integers.
+   passed two integers.  This is the equivalent of the Python expression ``o1 / o2``.
 
 
 .. c:function:: PyObject* PyNumber_Remainder(PyObject *o1, PyObject *o2)
@@ -180,6 +180,7 @@ Number Protocol
    floating point numbers are approximate; it is not possible to represent all real
    numbers in base two.  This function can return a floating point value when
    passed two integers.  The operation is done *in-place* when *o1* supports it.
+   This is the equivalent of the Python statement ``o1 /= o2``.
 
 
 .. c:function:: PyObject* PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2)
@@ -281,6 +282,6 @@ Number Protocol
 
 .. c:function:: int PyIndex_Check(PyObject *o)
 
-   Returns ``1`` if *o* is an index integer (has the nb_index slot of  the
-   tp_as_number structure filled in), and ``0`` otherwise.
+   Returns ``1`` if *o* is an index integer (has the ``nb_index`` slot of the
+   ``tp_as_number`` structure filled in), and ``0`` otherwise.
    This function always succeeds.

Doc/c-api/object.rst

@@ -93,7 +93,7 @@ Object Protocol
    return ``0`` on success.  This is the equivalent of the Python statement
    ``o.attr_name = v``.
 
-   If *v* is ``NULL``, the attribute is deleted, however this feature is
+   If *v* is ``NULL``, the attribute is deleted, but this feature is
    deprecated in favour of using :c:func:`PyObject_DelAttrString`.
 
 
@@ -291,7 +291,7 @@ Object Protocol
    of object *o*. On failure, raises :exc:`SystemError` and returns ``NULL``.  This
    is equivalent to the Python expression ``type(o)``. This function increments the
    reference count of the return value. There's really no reason to use this
-   function instead of the common expression ``o->ob_type``, which returns a
+   function instead of the :c:func:`Py_TYPE()` function, which returns a
    pointer of type :c:type:`PyTypeObject*`, except when the incremented reference
    count is needed.
 

Doc/c-api/sequence.rst

@@ -8,10 +8,10 @@ Sequence Protocol
 
 .. c:function:: int PySequence_Check(PyObject *o)
 
-   Return ``1`` if the object provides sequence protocol, and ``0`` otherwise.
+   Return ``1`` if the object provides the sequence protocol, and ``0`` otherwise.
    Note that it returns ``1`` for Python classes with a :meth:`__getitem__`
-   method unless they are :class:`dict` subclasses since in general case it
-   is impossible to determine what the type of keys it supports.  This
+   method, unless they are :class:`dict` subclasses, since in general it
+   is impossible to determine what type of keys the class supports.  This
    function always succeeds.
 
 
@@ -69,7 +69,7 @@ Sequence Protocol
    is the equivalent of the Python statement ``o[i] = v``.  This function *does
    not* steal a reference to *v*.
 
-   If *v* is ``NULL``, the element is deleted, however this feature is
+   If *v* is ``NULL``, the element is deleted, but this feature is
    deprecated in favour of using :c:func:`PySequence_DelItem`.
 
 
@@ -147,7 +147,7 @@ Sequence Protocol
 
    Returns the length of *o*, assuming that *o* was returned by
    :c:func:`PySequence_Fast` and that *o* is not ``NULL``.  The size can also be
-   gotten by calling :c:func:`PySequence_Size` on *o*, but
+   retrieved by calling :c:func:`PySequence_Size` on *o*, but
    :c:func:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a
    list or tuple.
 

Doc/c-api/set.rst

@@ -13,7 +13,7 @@ Set Objects
    object: frozenset
 
 This section details the public API for :class:`set` and :class:`frozenset`
-objects.  Any functionality not listed below is best accessed using the either
+objects.  Any functionality not listed below is best accessed using either
 the abstract object protocol (including :c:func:`PyObject_CallMethod`,
 :c:func:`PyObject_RichCompareBool`, :c:func:`PyObject_Hash`,
 :c:func:`PyObject_Repr`, :c:func:`PyObject_IsTrue`, :c:func:`PyObject_Print`, and
@@ -31,7 +31,7 @@ the abstract object protocol (including :c:func:`PyObject_CallMethod`,
    in that it is a fixed size for small sets (much like tuple storage) and will
    point to a separate, variable sized block of memory for medium and large sized
    sets (much like list storage). None of the fields of this structure should be
-   considered public and are subject to change.  All access should be done through
+   considered public and all are subject to change.  All access should be done through
    the documented API rather than by manipulating the values in the structure.
 
 
@@ -125,7 +125,7 @@ or :class:`frozenset` or instances of their subtypes.
 .. c:function:: int PySet_Add(PyObject *set, PyObject *key)
 
    Add *key* to a :class:`set` instance.  Also works with :class:`frozenset`
-   instances (like :c:func:`PyTuple_SetItem` it can be used to fill-in the values
+   instances (like :c:func:`PyTuple_SetItem` it can be used to fill in the values
    of brand new frozensets before they are exposed to other code).  Return ``0`` on
    success or ``-1`` on failure. Raise a :exc:`TypeError` if the *key* is
    unhashable. Raise a :exc:`MemoryError` if there is no room to grow.  Raise a

Doc/c-api/structures.rst

@@ -461,7 +461,7 @@ Accessing attributes of extension types
    +=============+==================+===================================+
    | name        | const char \*    | attribute name                    |
    +-------------+------------------+-----------------------------------+
-   | get         | getter           | C Function to get the attribute   |
+   | get         | getter           | C function to get the attribute   |
    +-------------+------------------+-----------------------------------+
    | set         | setter           | optional C function to set or     |
    |             |                  | delete the attribute, if omitted  |

Doc/c-api/sys.rst

@@ -185,7 +185,7 @@ Operating System Utilities
 
    Return a pointer to a newly allocated byte string, use :c:func:`PyMem_Free`
    to free the memory. Return ``NULL`` on encoding error or memory allocation
-   error
+   error.
 
    If error_pos is not ``NULL``, ``*error_pos`` is set to ``(size_t)-1`` on
    success,  or set to the index of the invalid character on encoding error.
@@ -205,7 +205,7 @@ Operating System Utilities
 
    .. versionchanged:: 3.8
       The function now uses the UTF-8 encoding on Windows if
-      :c:data:`Py_LegacyWindowsFSEncodingFlag` is zero;
+      :c:data:`Py_LegacyWindowsFSEncodingFlag` is zero.
 
 
 .. _systemfunctions:
@@ -336,7 +336,7 @@ accessible to C code.  They all work with the current interpreter thread's
 .. c:function:: int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)
 
    Append the callable *hook* to the list of active auditing hooks.
-   Return zero for success
+   Return zero on success
    and non-zero on failure. If the runtime has been initialized, also set an
    error on failure. Hooks added through this API are called for all
    interpreters created by the runtime.