try to improve docs

jcupitt · jcupitt · commit a77519f7c3a1 · 2022-03-22T09:10:34.000Z
see #2733 (reply in thread)
diff --git a/cplusplus/include/vips/VImage8.h b/cplusplus/include/vips/VImage8.h
@@ -988,9 +988,16 @@ class VImage : public VObject
 	}
 
 	/**
-	 * 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
@@ -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(). 
  *

Original file line number	Diff line number	Diff line change
`@@ -3309,10 +3309,17 @@ vips_image_rewind_output( VipsImage *image )`
`3309`	`3309`	`* vips_image_copy_memory:`
`3310`	`3310`	`* @image: image to copy to a memory buffer`
`3311`	`3311`	`*`
`3312`		`- * Make an image which is an area of memory.`
	`3312`	`+ * This function allocates memory, renders @image into it, builds a new`
	`3313`	`+ * image around the memory area, and returns that.`
`3313`	`3314`	`*`
`3314`		`- * If @image is already a memory buffer, just ref and return. If it's a file on`
`3315`		`- * disc or a partial, allocate memory and copy the image to it.`
	`3315`	`+ * If the image is already a simple area of memory, it just refs @image and`
	`3316`	`+ * returns it.`
	`3317`	`+ *`
	`3318`	`+ * Call this before using the draw operations to make sure you have a`
	`3319`	`+ * memory image that can be modified.`
	`3320`	`+ *`
	`3321`	`+ * vips_image_copy() adds a null "copy" node to a pipeline. Use that`
	`3322`	`+ * instead if you want to change metadata and not pixels.`
`3316`	`3323`	`*`
`3317`	`3324`	`* This operation is thread-safe, unlike vips_image_wio_input().`
`3318`	`3325`	`*`