diff --git a/cplusplus/include/vips/VImage8.h b/cplusplus/include/vips/VImage8.h
index e719143f..70224de9 100644
--- a/cplusplus/include/vips/VImage8.h
+++ b/cplusplus/include/vips/VImage8.h
@@ -988,9 +988,16 @@ public:
 	}
 
 	/**
-	 * Make a new image by rendering self to a large memory area, 
-	 * wrapping a VImage around it, and copying all metadata over from 
-	 * self.
+	 * This operation allocates memory, renders self into it, builds a new
+	 * image around the memory area, and returns that.
+	 *
+	 * If the image is already a simple area of memory, it does nothing.
+	 *
+	 * Call this before using the draw operations to make sure you have a
+	 * memory image that can be modified.
+	 *
+	 * VImage::copy() adds a null "copy" node to a pipeline. Use that
+	 * instead if you want to change metadata and not pixels.
 	 */ 
 	VImage 
 	copy_memory() const
diff --git a/libvips/iofuncs/image.c b/libvips/iofuncs/image.c
index e3332cdf..3c0489d7 100644
--- a/libvips/iofuncs/image.c
+++ b/libvips/iofuncs/image.c
@@ -3309,10 +3309,17 @@ vips_image_rewind_output( VipsImage *image )
  * vips_image_copy_memory:
  * @image: image to copy to a memory buffer
  *
- * Make an image which is an area of memory. 
+ * This function allocates memory, renders @image into it, builds a new
+ * image around the memory area, and returns that.
  *
- * If @image is already a memory buffer, just ref and return. If it's a file on
- * disc or a partial, allocate memory and copy the image to it. 
+ * If the image is already a simple area of memory, it just refs @image and
+ * returns it.
+ *
+ * Call this before using the draw operations to make sure you have a
+ * memory image that can be modified.
+ *
+ * vips_image_copy() adds a null "copy" node to a pipeline. Use that
+ * instead if you want to change metadata and not pixels.
  *
  * This operation is thread-safe, unlike vips_image_wio_input(). 
  *