create-image: Expand documentation (bug#33990)

* lisp/image.el (create-image): Discuss default for :scale in the doc
string.

1 files changed, 8 insertions, 1 deletions

diff --git a/lisp/image.el b/lisp/image.el
index b49f1b3aa5a..3019da556b3 100644
--- a/lisp/image.el
+++ b/lisp/image.el
@@ -413,13 +413,20 @@ must be available."
 (defun create-image (file-or-data &optional type data-p &rest props)
   "Create an image.
 FILE-OR-DATA is an image file name or image data.
+
 Optional TYPE is a symbol describing the image type.  If TYPE is omitted
 or nil, try to determine the image type from its first few bytes
 of image data.  If that doesn't work, and FILE-OR-DATA is a file name,
 use its file extension as image type.
+
 Optional DATA-P non-nil means FILE-OR-DATA is a string containing image data.
+
 Optional PROPS are additional image attributes to assign to the image,
-like, e.g. `:mask MASK'.
+like, e.g. `:mask MASK'.  If the property `:scale' is not given and the
+display has a high resolution (more exactly, when the average width of a
+character in the default font is more than 10 pixels), the image is
+automatically scaled up in proportion to the default font.
+
 Value is the image created, or nil if images of type TYPE are not supported.
 
 Images should not be larger than specified by `max-image-size'.