Improve 'put-image' documentation

* doc/lispref/display.texi (Showing Images): Mention that it returns the
created overlay.
* lisp/image.el (put-image): And here.

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 55885b7438d70be1b7b657c719521aa5d5bcd651..139fdcfc1019399b10ca78f75777a618fa7437ca 100644 (file)
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -7093,7 +7093,9 @@ buffer's text.
 
 Internally, this function creates an overlay, and gives it a
 @code{before-string} property containing text that has a @code{display}
-property whose value is the image.  (Whew! that was a mouthful@dots{})
+property whose value is the image.  (Whew! that was a mouthful@dots{}).
+It returns the created overlay upon success, and also sets its
+@code{put-image} property to @code{t}.
 @end defun
 
 @defun remove-images start end &optional buffer

diff --git a/lisp/image.el b/lisp/image.el
index c75c8ff765a45c60c7e7aa11b592512b4dd7ccda..e16bd989ce70d1dff910f1d63b92666091fd73e4 100644 (file)
--- a/lisp/image.el
+++ b/lisp/image.el
@@ -638,7 +638,9 @@ IMAGE must be an image created with `create-image' or `defimage'.
 IMAGE is displayed by putting an overlay into the current buffer with a
 `before-string' STRING that has a `display' property whose value is the
 image.  STRING defaults to \"x\" if it's nil or omitted.
-The overlay created by this function has the `put-image' property set to t.
+Upon success, this function returns the created overlay with its
+`put-image' property set to t.
+
 POS may be an integer or marker.
 AREA is where to display the image.  AREA nil or omitted means
 display it in the text area, a value of `left-margin' means