Address Benedikt's review

Author: vstinner

peps/pep-0782.rst

@@ -106,10 +106,20 @@ Create, Finish, Discard
    Similar to :c:func:`PyBytesWriter_Finish`, but resize the writer
    using *buf* pointer before creating the :class:`bytes` object.
 
+   Pseudo-code::
+
+       Py_ssize_t size = (char*)buf - (char*)PyBytesWriter_GetData(writer);
+       return PyBytesWriter_FinishWithSize(writer, size);
+
+   Set an exception and return ``NULL`` if *buf* pointer is invalid:
+   outside the internal buffer bounds.
+
 .. c:function:: void PyBytesWriter_Discard(PyBytesWriter *writer)
 
    Discard a :c:type:`PyBytesWriter` created by :c:func:`PyBytesWriter_Create`.
 
+   Do nothing if *writer* is ``NULL``.
+
    The writer instance is invalid after the call.
 
 High-level API
@@ -155,6 +165,8 @@ Low-level API
    Resize the writer to *size* bytes. It can be used to enlarge or to
    shrink the writer.
 
+   Newly allocated bytes are left uninitialized.
+
    On success, return ``0``.
    On error, set an exception and return ``-1``.
 
@@ -164,6 +176,8 @@ Low-level API
 
    Resize the writer by adding *grow* bytes to the current writer size.
 
+   Newly allocated bytes are left uninitialized.
+
    On success, return ``0``.
    On error, set an exception and return ``-1``.
 
@@ -174,6 +188,16 @@ Low-level API
    Similar to :c:func:`PyBytesWriter_Grow`, but update also the *buf*
    pointer.
 
+   On error, set an exception and return ``NULL``.
+
+   Pseudo-code::
+
+       Py_ssize_t pos = (char*)buf - (char*)PyBytesWriter_GetData(writer);
+       if (PyBytesWriter_Grow(writer, size) < 0) {
+           return NULL;
+       }
+       return (char*)PyBytesWriter_GetData(writer) + pos;
+
 
 Overallocation
 --------------