; Improve documentation of a recent change in Gnus

* lisp/image.el (find-image): Doc fix.
* lisp/gnus/gnus.el (gnus-mode-line-logo): Fix doc string and
:type texts.  Add :version.  (Bug#68985)

(cherry picked from commit 6195a57b8e8ebff4eaaf4ff8d62719cbd55f579f)

diff --git a/etc/NEWS b/etc/NEWS
index 27752faecaa28912406b37374a4b467988f2007e..4f32bf532473d61f161fd8f321c2503b022a13db 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1205,6 +1205,7 @@ The gmane.org website is, sadly, down since a number of years with no
 prospect of it coming back.  Therefore, it is no longer valid to set
 the user option 'nnweb-type' to 'gmane'.
 
+---
 *** New user option 'gnus-mode-line-logo'.
 This allows the user to either disable the display of any logo or
 specify which logo will be displayed as part of the

diff --git a/lisp/gnus/gnus.el b/lisp/gnus/gnus.el
index cf4c3f7841c08b4307d1101662fc34ce356f0c98..dab66b6020545b675c1d88b9f2a06d098c3a7bee 100644 (file)
--- a/lisp/gnus/gnus.el
+++ b/lisp/gnus/gnus.el
@@ -313,18 +313,19 @@ be set in `.emacs' instead."
   '((:type svg :file "gnus-pointer.svg" :ascent center)
      (:type xpm :file "gnus-pointer.xpm" :ascent center)
      (:type xbm :file "gnus-pointer.xbm" :ascent center))
-  "Gnus logo displayed in mode-line.
+  "Image spec for the Gnus logo to be displayed in mode-line.
 
-If non-nil, it should be a list of image specifications that will be
-given as first argument to `find-image', which see.  Then, in case of a
-graphical display, the specified Gnus logo will be displayed as part of
+If non-nil, it should be a list of image specifications to be passed
+as the first argument to `find-image', which see.  Then, if the display
+is capable of showing images, the Gnus logo will be displayed as part of
 the buffer-identification in the mode-line of Gnus-buffers.
 
-If nil, no logo will be displayed."
+If nil, there will be no Gnus logo in the mode-line."
   :group 'gnus-visual
   :type '(choice
-           (repeat :tag "List of image specifications" (plist))
-           (const :tag "No logo" nil)))
+           (repeat :tag "List of Gnus logo image specifications" (plist))
+           (const :tag "Don't display Gnus logo" nil))
+  :version "30.1")
 
 (defun gnus-mode-line-buffer-identification (line)
   (let* ((str (car-safe line))

diff --git a/lisp/image.el b/lisp/image.el
index 73801f88d1e8d1800caa552cb4db1953e74d07bc..2ebce59a98c83a0c53d4856eb77cd0ea44ff659e 100644 (file)
--- a/lisp/image.el
+++ b/lisp/image.el
@@ -759,21 +759,25 @@ BUFFER nil or omitted means use the current buffer."
 
 ;;;###autoload
 (defun find-image (specs &optional cache)
-  "Find an image, choosing one of a list of image specifications.
+  "Find an image that satisfies one of a list of image specifications.
 
 SPECS is a list of image specifications.
 
-Each image specification in SPECS is a property list.  The contents of
-a specification are image type dependent.  All specifications must at
-least contain either the property `:file FILE' or `:data DATA',
-where FILE is the file to load the image from, and DATA is a string
-containing the actual image data.  If the property `:type TYPE' is
-omitted or nil, try to determine the image type from its first few
+Each image specification in SPECS is a property list.  The
+contents of a specification are image type dependent; see the
+info node `(elisp)Image Descriptors' for details.  All specifications
+must at least contain either the property `:file FILE' or `:data DATA',
+where FILE is the file from which to load the image, and DATA is a
+string containing the actual image data.  If the property `:type 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 the property `:file
-FILE' provide a file name, use its file extension as image type.
-If `:type TYPE' is provided, it must match the actual type
-determined for FILE or DATA by `create-image'.  Return nil if no
-specification is satisfied.
+FILE' provide a file name, use its file extension as idication of the
+image type. If `:type TYPE' is provided, it must match the actual type
+determined for FILE or DATA by `create-image'.
+
+The function returns the image specification for the first specification
+in the list whose TYPE is supported and FILE, if specified, exists.  It
+returns nil if no specification in the list can be satisfied.
 
 If CACHE is non-nil, results are cached and returned on subsequent calls.