Improve docs on buffer/buffer obj ambiguity

inducer · Nov 14, 2014 · d1c9724 · d1c9724
1 parent aaf35ed
commit d1c9724
Show file tree

Hide file tree

Showing 2 changed files with 18 additions and 0 deletions.
diff --git a/doc/runtime.rst b/doc/runtime.rst
@@ -386,6 +386,15 @@ Buffers
 
     :class:`Buffer` inherits from :class:`MemoryObject`.
 
+    .. note::
+
+        Python also defines a type of `buffer object
+        <https://docs.python.org/3.4/c-api/buffer.html>`_,
+        and PyOpenCL interacts with those, too, as the host-side
+        target of :func:`enqueue_copy`. Make sure to always be
+        clear on whether a :class:`Buffer` or a Python buffer
+        object is needed.
+
     Note that actual memory allocation in OpenCL may be deferred.
     Buffers are attached to a :class:`Context` and are only
     moved to a device once the buffer is used on that device.

diff --git a/pyopencl/__init__.py b/pyopencl/__init__.py
@@ -954,6 +954,15 @@ def enqueue_copy(queue, dest, src, **kwargs):
     :return: A :class:`NannyEvent` if the transfer involved a
         host-side buffer, otherwise an :class:`Event`.
 
+    .. note::
+
+        Two types of 'buffer' occur in the arguments to this function,
+        :class:`Buffer` and 'host-side buffers'. The latter are
+        defined by Python and commonly called `buffer objects
+        <https://docs.python.org/3.4/c-api/buffer.html>`_.
+        Make sure to always be clear on whether a :class:`Buffer` or a
+        Python buffer object is needed.
+
     .. ------------------------------------------------------------------------
     .. rubric :: Transfer :class:`Buffer` ↔ host
     .. ------------------------------------------------------------------------