Issue #12965: Clean up C-API docs for PyLong_AsLong(AndOverflow); clarify that __int__ will be called for non-PyLongs

Doc/c-api/long.rst

@@ -108,26 +108,29 @@ All integers are implemented as "long" integer objects of arbitrary size.
 
 
 .. XXX alias PyLong_AS_LONG (for now)
-.. c:function:: long PyLong_AsLong(PyObject *pylong)
+.. c:function:: long PyLong_AsLong(PyObject *obj)
 
    .. index::
       single: LONG_MAX
       single: OverflowError (built-in exception)
 
-   Return a C :c:type:`long` representation of the contents of *pylong*.  If
+   Return a C :c:type:`long` representation of *obj*.  If *obj* is not an
-   *pylong* is greater than :const:`LONG_MAX`, raise an :exc:`OverflowError`,
+   instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method
-   and return -1. Convert non-long objects automatically to long first,
+   (if present) to convert it to a :c:type:`PyLongObject`.
-   and return -1 if that raises exceptions.
 
-.. c:function:: long PyLong_AsLongAndOverflow(PyObject *pylong, int *overflow)
+   Raise :exc:`OverflowError` if the value of *obj* is out of range for a
+   :c:type:`long`.
 
-   Return a C :c:type:`long` representation of the contents of
+.. c:function:: long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)
-   *pylong*.  If *pylong* is greater than :const:`LONG_MAX` or less
+
-   than :const:`LONG_MIN`, set *\*overflow* to ``1`` or ``-1``,
+   Return a C :c:type:`long` representation of *obj*.  If *obj* is not an
-   respectively, and return ``-1``; otherwise, set *\*overflow* to
+   instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method
-   ``0``.  If any other exception occurs (for example a TypeError or
+   (if present) to convert it to a :c:type:`PyLongObject`.
-   MemoryError), then ``-1`` will be returned and *\*overflow* will
+
-   be ``0``.
+   If the value of *obj* is greater than :const:`LONG_MAX` or less than
+   :const:`LONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively, and
+   return ``-1``; otherwise, set *\*overflow* to ``0``.  If any other exception
+   occurs set *\*overflow* to ``0`` and return ``-1`` as usual.
 
 
 .. c:function:: PY_LONG_LONG PyLong_AsLongLongAndOverflow(PyObject *pylong, int *overflow)