From: Robert Pluim <rpluim@gmail.com>
Date: Tue, 9 Jul 2024 15:14:45 +0000 (+0200)
Subject: Improve 'put-image' documentation
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=e42ae7682962bf9cf2f4e215422a1767bb90e397;p=emacs.git

Improve 'put-image' documentation

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

(cherry picked from commit 945335fec1e9349d05291c9abe0730777840f5b9)
---

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 9cd398da9f8..f10595855b6 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -7123,7 +7123,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 c75c8ff765a..e16bd989ce7 100644
--- 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