emacs-29 2591eb1190a: Improve documentation of 'minibuffer-message'

[Eli Zaretskii]

branch: emacs-29
commit 2591eb1190a24074357a2f178bc02ddc86c94b43
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Improve documentation of 'minibuffer-message'
    
    * doc/lispref/minibuf.texi (Minibuffer Misc): Clarify that
    'minibuffer-message' behaves like 'message' if called from a
    buffer that is not a minibuffer.
    
    * lisp/minibuffer.el (minibuffer-message)
    (set-minibuffer-message, clear-minibuffer-message): Doc fixes.
    (Bug#64165)
---
 doc/lispref/minibuf.texi | 24 +++++++++++++++++-------
 lisp/minibuffer.el       | 24 +++++++++++++++++-------
 2 files changed, 34 insertions(+), 14 deletions(-)

diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 9a386ff310d..52eea3b9535 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -2805,13 +2805,23 @@ minibuffer window, it returns @code{nil}.
 
 @vindex minibuffer-message-timeout
 @defun minibuffer-message string &rest args
-This function displays @var{string} temporarily at the end of the
-minibuffer text, for a few seconds, or until the next input event
-arrives, whichever comes first.  The variable
-@code{minibuffer-message-timeout} specifies the number of seconds to
-wait in the absence of input.  It defaults to 2.  If @var{args} is
-non-@code{nil}, the actual message is obtained by passing @var{string}
-and @var{args} through @code{format-message}.  @xref{Formatting Strings}.
+This function is like @code{message} (@pxref{Displaying Messages}),
+but it displays the messages specially when the user types in the
+minibuffer, typically because Emacs prompted the user for some input.
+When the minibuffer is the current buffer, this function displays the
+message specified by @var{string} temporarily at the end of the
+minibuffer text, and thus avoids hiding the minibuffer text by the
+echo-area display of the message.  It leaves the message on display
+for a few seconds, or until the next input event arrives, whichever
+comes first.  The variable @code{minibuffer-message-timeout} specifies
+the number of seconds to wait in the absence of input.  It defaults to
+2.  If @var{args} is non-@code{nil}, the actual message is obtained by
+passing @var{string} and @var{args} through @code{format-message}.
+@xref{Formatting Strings}.
+
+If called when the minibuffer is not the current buffer, this function
+just calls @code{message}, and thus @var{string} will be shown in the
+echo-area.
 @end defun
 
 @deffn Command minibuffer-inactive-mode
diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index 41eb95fd20f..4aa1ab3e890 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -715,11 +715,21 @@ for use at QPOS."
   "Text properties added to the text shown by `minibuffer-message'.")
 
 (defun minibuffer-message (message &rest args)
-  "Temporarily display MESSAGE at the end of the minibuffer.
-The text is displayed for `minibuffer-message-timeout' seconds,
-or until the next input event arrives, whichever comes first.
-Enclose MESSAGE in [...] if this is not yet the case.
-If ARGS are provided, then pass MESSAGE through `format-message'."
+  "Temporarily display MESSAGE at the end of minibuffer text.
+This function is designed to be called from the minibuffer, i.e.,
+when Emacs prompts the user for some input, and the user types
+into the minibuffer.  If called when the current buffer is not
+the minibuffer, this function just calls `message', and thus
+displays MESSAGE in the echo-area.
+When called from the minibuffer, this function displays MESSAGE
+at the end of minibuffer text for `minibuffer-message-timeout'
+seconds, or until the next input event arrives, whichever comes first.
+It encloses MESSAGE in [...] if it is not yet enclosed.
+The intent is to show the message without hiding what the user typed.
+If ARGS are provided, then the function first passes MESSAGE
+through `format-message'.
+If some of the minibuffer text has the `minibuffer-message' text
+property, MESSAGE is shown at that position instead of EOB."
   (if (not (minibufferp (current-buffer) t))
       (progn
         (if args
@@ -796,7 +806,7 @@ The minibuffer message functions include 
`minibuffer-message' and
       (next-single-property-change pt 'minibuffer-message nil (point-max)))))
 
 (defun set-minibuffer-message (message)
-  "Temporarily display MESSAGE at the end of the minibuffer.
+  "Temporarily display MESSAGE at the end of the active minibuffer window.
 If some part of the minibuffer text has the `minibuffer-message' property,
 the message will be displayed before the first such character, instead of
 at the end of the minibuffer.
@@ -954,7 +964,7 @@ is at its default value `grow-only'."
                multi-message-separator)))
 
 (defun clear-minibuffer-message ()
-  "Clear minibuffer message.
+  "Clear message temporarily shown in the minibuffer.
 Intended to be called via `clear-message-function'."
   (when (not noninteractive)
     (when (timerp minibuffer-message-timer)