[docs] Document that PyUnicode_AsUTF8() returns a null-terminated string (issue 23088)

[rdmurray at bitdance.com]

http://bugs.python.org/review/23088/diff/14381/Doc/c-api/bytearray.rst
File Doc/c-api/bytearray.rst (right):

http://bugs.python.org/review/23088/diff/14381/Doc/c-api/bytearray.rst#newcode68
Doc/c-api/bytearray.rst:68: null byte appended, even when the array
already contains null bytes.
Based on the other changes, I think you should drop the "even when"
clause.  There is always an extra null byte appended to whatever the
Python content of the object is, and it actually makes it more confusing
to add that extra clause, IMO.

http://bugs.python.org/review/23088/diff/14381/Doc/c-api/bytes.rst
File Doc/c-api/bytes.rst (right):

http://bugs.python.org/review/23088/diff/14381/Doc/c-api/bytes.rst#newcode139
Doc/c-api/bytes.rst:139: Return the contents of *o*.  The pointer refers
to the internal buffer of
Return a pointer to the contents of *o*.

http://bugs.python.org/review/23088/diff/14381/Doc/c-api/bytes.rst#newcode141
Doc/c-api/bytes.rst:141: bytes object already contains null bytes.  The
data must not be
OK, this makes no sense to me.  What exactly is the object here?  It
sounds like it is a bytes object, in which case it makes no logical
sense to say "even when the bytes object already contains null bytes". 
Is the internal buffer of the object N+1 bytes, where the first N bytes
comprise the "bytes object" from the point of view of Python, but
internally the buffer that holds those bytes has an additional
(len(bytesobject)+1) position that contains a null byte?  If that is the
case, I think this should read "The pointer refers to the internal
buffer of *o*, which consists of len(o)+1 bytes, the last of which is
always a null byte (regardless of whether or not there are any other
null bytes in the buffer)."

http://bugs.python.org/review/23088/diff/14381/Doc/c-api/bytes.rst#newcode155
Doc/c-api/bytes.rst:155: Return a null-terminated representation of the
contents of the object *obj*
If you removed 'representation' above, you should do it here to (and
that seems to make sense to me).

http://bugs.python.org/review/23088/diff/14381/Doc/c-api/bytes.rst#newcode162
Doc/c-api/bytes.rst:162: The buffer refers to an internal buffer of
*obj*, not a copy. The data
If I'm right in my comment above, this should probably say "buffer of
*obj*, which includes an additional null byte after the bytes that
constitute the content of the bytes object".

http://bugs.python.org/review/23088/