Doc clarification / edification on the semantics of the 'w*' format unit.

diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst
index 3c0f4b98cdbaa9a57b080f180b41d1c19f2b44d5..ed62deaec1c87c23f02adc888263bfdf010ba924 100644 (file)
--- a/Doc/c-api/arg.rst
+++ b/Doc/c-api/arg.rst
@@ -152,7 +152,7 @@ Unless otherwise stated, buffers are not NUL-terminated.
    any conversion.  Raises :exc:`TypeError` if the object is not a Unicode
    object.  The C variable may also be declared as :c:type:`PyObject\*`.
 
-``w*`` (:class:`bytearray` or read-write byte-oriented buffer) [Py_buffer]
+``w*`` (read-write :term:`bytes-like object`) [Py_buffer]
    This format accepts any object which implements the read-write buffer
    interface. It fills a :c:type:`Py_buffer` structure provided by the caller.
    The buffer may contain embedded null bytes. The caller have to call

diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index 578fd113f8897ab7f7446f3492e18b4def300984..57c6ddd72523cb5a2ca9c879c089feb6701c1be8 100644 (file)
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -88,10 +88,17 @@ Glossary
    bytes-like object
       An object that supports the :ref:`bufferobjects`, like :class:`bytes`,
       :class:`bytearray` or :class:`memoryview`.  Bytes-like objects can
-      be used for various operations that expect binary data, such as
-      compression, saving to a binary file or sending over a socket.
-      Some operations need the binary data to be mutable, in which case
-      not all bytes-like objects can apply.
+      be used for various operations that work with binary data; these include
+      compression, saving to a binary file, and sending over a socket.
+
+      Some operations need the binary data to be mutable.  The documentation
+      often refers to these as "read-write bytes-like objects".  Example
+      mutable buffer objects include :class:`bytearray` and a
+      :class:`memoryview` of a :class:`bytearray`.
+      Other operations require the binary data to be stored in
+      immutable objects ("read-only bytes-like objects"); examples
+      of these include :class:`bytes` and a :class:`memoryview`
+      of a :class:`bytes` object.
 
    bytecode
       Python source code is compiled into bytecode, the internal representation