PEP 757: address gpshead's review (#4144)

Co-authored-by: Hugo van Kemenade <[email protected]>

peps/pep-0757.rst

@@ -79,7 +79,7 @@ functions.
       - ``1`` for most significant digit first
       - ``-1`` for least significant digit first
 
-   .. c:member:: int8_t endianness
+   .. c:member:: int8_t digit_endianness
 
       Digit endianness:
 
@@ -177,19 +177,20 @@ create a Python :class:`int` object from a digits array.
 
    Create a :c:type:`PyLongWriter`.
 
-   On success, set *\*digits* and return a writer.
+   On success, allocate *\*digits* and return a writer.
    On error, set an exception and return ``NULL``.
 
    *negative* is ``1`` if the number is negative, or ``0`` otherwise.
 
-   *ndigits* is the number of digits in the *digits* array. It must be
-   greater than or equal to 0.
+   *ndigits* is the number of digits in the *digits* array.  It must be
+   greater than 0.
 
-   The caller can either initialize the array of digits *digits* and then call
-   :c:func:`PyLongWriter_Finish` to get a Python :class:`int`, or call
+   The caller can either initialize the array of digits *digits* and then
+   either call :c:func:`PyLongWriter_Finish` to get a Python :class:`int` or
    :c:func:`PyLongWriter_Discard` to destroy the writer instance.  Digits must
-   be in the range [``0``; ``(1 << sys.int_info.bits_per_digit) - 1``].  Unused
-   digits must be set to ``0``.
+   be in the range [``0``; ``(1 << bits_per_digit) - 1``]  (where the
+   :c:struct:`~PyLongLayout.bits_per_digit` is the number of bits per digit).
+   The unused most-significant digits must be set to ``0``.
 
 
 On CPython 3.14, the :c:func:`PyLongWriter_Create` implementation is a thin
@@ -206,11 +207,15 @@ wrapper to the private :c:func:`!_PyLong_New()` function.
    The function takes care of normalizing the digits and converts the
    object to a compact integer if needed.
 
+   The writer instance is invalid after the call.
+
 
 .. c:function:: void PyLongWriter_Discard(PyLongWriter *writer)
 
    Discard a :c:type:`PyLongWriter` created by :c:func:`PyLongWriter_Create`.
 
+   The writer instance is invalid after the call.
+
 
 Optimize import for small integers
 ==================================
@@ -252,7 +257,7 @@ Code::
     int int_digits_order = layout->digits_order;
     size_t int_bits_per_digit = layout->bits_per_digit;
     size_t int_nails = int_digit_size*8 - int_bits_per_digit;
-    int int_endianness = layout->endianness;
+    int int_endianness = layout->digit_endianness;
 
 
 Export: :c:func:`PyLong_Export()` with gmpy2