gh-129813: Enhance PyBytesWriter documentation (#140152)

Co-authored-by: Antoine Pitrou <pitrou@free.fr>

diff --git a/Doc/c-api/bytes.rst b/Doc/c-api/bytes.rst
index 9bddfe4dce2f879fa946b82cb9b07a6f227bab39..865a9e5d2bf5d503af6657c4dd702e0fd1d8058f 100644 (file)
--- a/Doc/c-api/bytes.rst
+++ b/Doc/c-api/bytes.rst
@@ -259,6 +259,7 @@ Create, Finish, Discard
    If *size* is greater than zero, allocate *size* bytes, and set the
    writer size to *size*. The caller is responsible to write *size*
    bytes using :c:func:`PyBytesWriter_GetData`.
+   This function does not overallocate.
 
    On error, set an exception and return ``NULL``.
 
@@ -349,6 +350,8 @@ Low-level API
 
    Resize the writer to *size* bytes. It can be used to enlarge or to
    shrink the writer.
+   This function typically overallocates to achieve amortized performance when
+   resizing multiple times.
 
    Newly allocated bytes are left uninitialized.
 
@@ -360,6 +363,8 @@ Low-level API
 .. c:function:: int PyBytesWriter_Grow(PyBytesWriter *writer, Py_ssize_t grow)
 
    Resize the writer by adding *grow* bytes to the current writer size.
+   This function typically overallocates to achieve amortized performance when
+   resizing multiple times.
 
    Newly allocated bytes are left uninitialized.