diff --git a/doc/source/runtime.rst b/doc/source/runtime.rst
index f3f84867f71ec4fae91a6f9518c4206dff21194d..4dd2c14f9ebaa8e54a6e4709d8deada6534306b7 100644
--- a/doc/source/runtime.rst
+++ b/doc/source/runtime.rst
@@ -368,6 +368,15 @@ Buffers
 
     :class:`Buffer` is a subclass of :class:`MemoryObject`.
 
+    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.
+    That is also the point when out-of-memory errors will occur.
+    If you'd like to be sure that there's enough memory for
+    your allocation, either use :func:`enqueue_migrate_mem_objects`
+    (if available) or simply perform a small transfer to the
+    buffer. See also :class:`pyopencl.tools.ImmediateAllocator`.
+
     .. method:: get_sub_region(origin, size, flags=0)
 
         Only available in OpenCL 1.1 and newer.
diff --git a/doc/source/tools.rst b/doc/source/tools.rst
index f2f9b0273d73ca768b7ad89a7402e65dcde88292..361882e7e211568bf6e27d5792cba78953636295 100644
--- a/doc/source/tools.rst
+++ b/doc/source/tools.rst
@@ -35,8 +35,14 @@ the available memory.
     *mem_flags* takes its values from :class:`pyopencl.mem_flags` and corresponds
     to the *flags* argument of :class:`pyopencl.Buffer`. DeferredAllocator
     has the same semantics as regular OpenCL buffer allocation, i.e. it may
-    promise memory to be available that later on (in any call to a buffer-using
-    CL function).
+    promise memory to be available that may (in any call to a buffer-using
+    CL function) turn out to not exist later on. (Allocations in CL are
+    bound to contexts, not devices, and memory availability depends on which
+    device the buffer is used with.)
+
+    .. versionchanged::
+        In version 2012.2, :class:`CLAllocator` was deprecated and replaced
+        by :class:`DeferredAllocator`.
 
     .. method:: __call__(size)
 
@@ -50,13 +56,19 @@ the available memory.
     promise memory to be available that later on (in any call to a buffer-using
     CL function).
 
+    .. versionadded:: 2012.2
+
     .. method:: __call__(size)
 
         Allocate a :class:`pyopencl.Buffer` of the given *size*.
 
-.. class:: MemoryPool(allocator=CLAllocator())
+.. class:: MemoryPool(allocator)
 
-    A memory pool for OpenCL device memory.
+    A memory pool for OpenCL device memory. *allocator* must be an instance of
+    one of the above classes, and should be an :class:`ImmediateAllocator`.
+    The memory pool assumes that allocation failures are reported
+    by the allocator immediately, and not in the OpenCL-typical
+    deferred manner.
 
     .. attribute:: held_blocks