From 68413fa107e9826291b4d20dd3f9930743c47119 Mon Sep 17 00:00:00 2001
From: Sergey B Kirpichev <skirpichev@gmail.com>
Date: Tue, 15 Oct 2024 12:43:41 +0300
Subject: [PATCH] PEP 757: edits, based on C-API WG feedback (#4026)

Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
---
 peps/pep-0757.rst | 35 ++++++++++++++++++++++-------------
 1 file changed, 22 insertions(+), 13 deletions(-)

diff --git a/peps/pep-0757.rst b/peps/pep-0757.rst
index 12b967c1b..e3208cf41 100644
--- a/peps/pep-0757.rst
+++ b/peps/pep-0757.rst
@@ -49,14 +49,19 @@ Specification
 Layout API
 ----------
 
-Data needed by `GMP <https://gmplib.org/>`_-like import-export functions.
+Data needed by `GMP <https://gmplib.org/>`_-like `import
+<https://gmplib.org/manual/Integer-Import-and-Export#index-mpz_005fimport>`_-`export
+<https://gmplib.org/manual/Integer-Import-and-Export#index-mpz_005fexport>`_
+functions.
 
 .. c:struct:: PyLongLayout
 
-   Layout of an array of digits, used by Python :class:`int` object.
+   Layout of an array of "digits" ("limbs" in the GMP terminology), used to
+   represent absolute value for arbitrary precision integers.
 
    Use :c:func:`PyLong_GetNativeLayout` to get the native layout of Python
-   :class:`int` objects.
+   :class:`int` objects, used internally for integers with "big enough"
+   absolute value.
 
    See also :data:`sys.int_info` which exposes similar information to Python.
 
@@ -148,8 +153,9 @@ Export API
    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 in :c:func:`PyLong_Export`, it's just
+a thin wrapper to expose Python :class:`int` internal digits array.
 
 
 .. c:function:: void PyLong_FreeExport(PyLongExport *export_long)
@@ -167,7 +173,8 @@ create a Python :class:`int` object from a digits array.
 
    A Python :class:`int` writer instance.
 
-   The instance must be destroyed by :c:func:`PyLongWriter_Finish`.
+   The instance must be destroyed by :c:func:`PyLongWriter_Finish` or
+   :c:func:`PyLongWriter_Discard`.
 
 
 .. c:function:: PyLongWriter* PyLongWriter_Create(int negative, Py_ssize_t ndigits, void **digits)
@@ -182,13 +189,15 @@ create a Python :class:`int` object from a digits array.
    *ndigits* is the number of digits in the *digits* array. It must be
    greater than or equal to 0.
 
-   The caller must initialize the array of digits *digits* and then call
-   :c:func:`PyLongWriter_Finish` to get a Python :class:`int`.  Digits must be
-   in the range [``0``; ``(1 << sys.int_info.bits_per_digit) - 1``].  Unused digits must
-   be set to ``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
+   :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``.
 
-   On CPython 3.14, the implementation is a thin wrapper to the private
-   :c:func:`!_PyLong_New()` function.
+
+On CPython 3.14, the :c:func:`PyLongWriter_Create` implementation is a thin
+wrapper to the private :c:func:`!_PyLong_New()` function.
 
 
 .. c:function:: PyObject* PyLongWriter_Finish(PyLongWriter *writer)
@@ -204,7 +213,7 @@ create a Python :class:`int` object from a digits array.
 
 .. c:function:: void PyLongWriter_Discard(PyLongWriter *writer)
 
-   Discard the internal object and destroy the writer instance.
+   Discard a :c:type:`PyLongWriter` created by :c:func:`PyLongWriter_Create`.
 
 
 Optimize import for small integers