PEP 757: Cleanup (#3979)

* endian => endianness
* Move text to function documentations
* Discussions: add link to the PEP discussion

Author: vstinner

peps/pep-0757.rst

@@ -75,7 +75,7 @@ Data needed by `GMP <https://gmplib.org/>`_-like import-export functions.
       - ``1`` for most significant digit first
       - ``-1`` for least significant digit first
 
-   .. c:member:: int8_t endian
+   .. c:member:: int8_t endianness
 
       Digit endianness:
 
@@ -89,11 +89,10 @@ Data needed by `GMP <https://gmplib.org/>`_-like import-export functions.
 
    See the :c:struct:`PyLongLayout` structure.
 
-
-The function must not be called before Python initialization nor after
-Python finalization. The returned layout is valid until Python is
-finalized. The layout is the same for all Python sub-interpreters and
-so it can be cached.
+   The function must not be called before Python initialization nor after
+   Python finalization. The returned layout is valid until Python is
+   finalized. The layout is the same for all Python sub-interpreters and
+   so it can be cached.
 
 
 Export API
@@ -141,16 +140,16 @@ Export API
    This function always succeeds if *obj* is a Python :class:`int` object or a
    subclass.
 
-   If *export_long.digits* is not ``NULL``, :c:func:`PyLong_FreeExport` must be
+   If *export_long->digits* is not ``NULL``, :c:func:`PyLong_FreeExport` must be
    called when the export is no longer needed.
 
-On CPython 3.14, no memory copy is needed, it's just a thin wrapper to
-expose Python int internal digits array.
+   On CPython 3.14, no memory copy is needed, it's just a thin wrapper to
+   expose Python int internal digits array.
 
-A private field of the :c:struct:`PyLongExport`, if
-:c:member:`~PyLongExport.digits` not ``NULL``, stores a strong reference to the
-Python :class:`int` object to make sure that that structure remains valid until
-:c:func:`PyLong_FreeExport()` is called.
+   If :c:member:`~PyLongExport.digits` not ``NULL``, a private field of
+   the :c:struct:`PyLongExport` structure stores a strong reference to
+   the Python :class:`int` object to make sure that that structure
+   remains valid until :c:func:`PyLong_FreeExport()` is called.
 
 
 .. c:function:: void PyLong_FreeExport(PyLongExport *export_long)
@@ -161,7 +160,8 @@ Python :class:`int` object to make sure that that structure remains valid until
 Import API
 ----------
 
-The :c:type:`PyLongWriter` API can be used to import an integer.
+The :c:type:`PyLongWriter` API can be used to import an integer:
+create a Python :class:`int` object from a digits array.
 
 .. c:struct:: PyLongWriter
 
@@ -187,8 +187,8 @@ The :c:type:`PyLongWriter` API can be used to import an integer.
    in the range [``0``; ``PyLong_BASE - 1``]. Unused digits must be set to
    ``0``.
 
-On CPython 3.14, the implementation is a thin wrapper to the private
-:c:func:`!_PyLong_New()` function.
+   On CPython 3.14, the implementation is a thin wrapper to the private
+   :c:func:`!_PyLong_New()` function.
 
 
 .. c:function:: PyObject* PyLongWriter_Finish(PyLongWriter *writer)
@@ -198,8 +198,8 @@ On CPython 3.14, the implementation is a thin wrapper to the private
    On success, return a Python :class:`int` object.
    On error, set an exception and return ``NULL``.
 
-:c:func:`PyLongWriter_Finish()` takes care of normalizing the digits and
-converts the object to a compact integer if needed.
+   The function takes care of normalizing the digits and converts the
+   object to a compact integer if needed.
 
 
 .. c:function:: void PyLongWriter_Discard(PyLongWriter *writer)
@@ -422,15 +422,22 @@ added.
 Discussions
 ===========
 
-* https://github.com/capi-workgroup/decisions/issues/35
-* https://github.com/python/cpython/pull/121339
-* https://github.com/python/cpython/issues/102471
+* Discourse: `PEP 757 – C API to import-export Python integers
+  <https://discuss.python.org/t/63895>`_
+* `C API Working Group decision issue #35
+  <https://github.com/capi-workgroup/decisions/issues/35>`_
+* `Pull request #121339
+  <https://github.com/python/cpython/pull/121339>`_
+* `Issue #102471
+  <https://github.com/python/cpython/issues/102471>`_:
+  The C-API for Python to C integer conversion is, to be frank, a mess.
 * `Add public function PyLong_GetDigits()
   <https://github.com/capi-workgroup/decisions/issues/31>`_
 * `Consider restoring _PyLong_New() function as public
   <https://github.com/python/cpython/issues/111415>`_
-* `gh-106320: Remove private _PyLong_New() function
-  <https://github.com/python/cpython/pull/108604>`_
+* `Pull request gh-106320
+  <https://github.com/python/cpython/pull/108604>`_:
+  Remove private _PyLong_New() function.
 
 
 Copyright