emacs-29 c1eac5b6586: Improve documentation of 'read-choice' and related symbols

[Eli Zaretskii]

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

    Improve documentation of 'read-choice' and related symbols
    
    * doc/lispref/commands.texi (Reading One Event):
    * lisp/subr.el (read-char-choice-use-read-key, read-char-choice)
    (read-char-choice-with-read-key, y-or-n-p-use-read-key): Improve
    documentation of these functions and variables.
---
 doc/lispref/commands.texi | 25 ++++++++++++++-------
 lisp/subr.el              | 56 +++++++++++++++++++++++++----------------------
 2 files changed, 47 insertions(+), 34 deletions(-)

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 20be706bebd..62a0939a47e 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -3215,15 +3215,24 @@ unspecified, the only fallback disabled is downcasing 
of the last
 event.
 @end defun
 
+@vindex read-char-choice-use-read-key
 @defun read-char-choice prompt chars &optional inhibit-quit
-This function uses @code{read-key} to read and return a single
-character.  It ignores any input that is not a member of @var{chars},
-a list of accepted characters.  Optionally, it will also ignore
-keyboard-quit events while it is waiting for valid input.  If you bind
-@code{help-form} (@pxref{Help Functions}) to a non-@code{nil} value
-while calling @code{read-char-choice}, then pressing @code{help-char}
-causes it to evaluate @code{help-form} and display the result.  It
-then continues to wait for a valid input character, or keyboard-quit.
+This function uses @code{read-from-minibuffer} to read and return a
+single character that is a member of @var{chars}, which should be a
+list of single characters.  It discards any input characters that are
+not members of @var{chars}, and shows a message to that effect.
+
+The optional argument @var{inhibit-quit} is by default ignored, but if
+the variable @code{read-char-choice-use-read-key} is non-@code{nil},
+this function uses @code{read-key} instead of
+@code{read-from-minibuffer}, and in that case @var{inhibit-quit}
+non-@code{nil} means ignore keyboard-quit events while waiting for
+valid input.  In addition, if @code{read-char-choice-use-read-key} is
+non-@code{nil}, binding @code{help-form} (@pxref{Help Functions}) to a
+non-@code{nil} value while calling this function causes it to evaluate
+@code{help-form} and display the result when the user presses
+@code{help-char}; it then continues to wait for a valid input
+character, or for keyboard-quit.
 @end defun
 
 @defun read-multiple-choice prompt choices &optional help-string show-help 
long-form
diff --git a/lisp/subr.el b/lisp/subr.el
index 8d27c831c96..a9d93e5fe5e 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -3196,34 +3196,38 @@ This function is used by the `interactive' code letter 
\"n\"."
     n))
 
 (defvar read-char-choice-use-read-key nil
-  "Prefer `read-key' when reading a character by `read-char-choice'.
-Otherwise, use the minibuffer.
+  "If non-nil, use `read-key' when reading a character by `read-char-choice'.
+Otherwise, use the minibuffer (this is the default).
 
-When using the minibuffer, the user is less constrained, and can
-use the normal commands available in the minibuffer, and can, for
-instance, switch to another buffer, do things there, and then
-switch back again to the minibuffer before entering the
-character.  This is not possible when using `read-key', but using
-`read-key' may be less confusing to some users.")
+When reading via the minibuffer, you can use the normal commands
+available in the minibuffer, and can, for instance, temporarily
+switch to another buffer, do things there, and then switch back
+to the minibuffer before entering the character.  This is not
+possible when using `read-key', but using `read-key' may be less
+confusing to some users.")
 
 (defun read-char-choice (prompt chars &optional inhibit-keyboard-quit)
-  "Read and return one of CHARS, prompting for PROMPT.
-Any input that is not one of CHARS is ignored.
-
-By default, the minibuffer is used to read the key
-non-modally (see `read-char-from-minibuffer').  If
-`read-char-choice-use-read-key' is non-nil, the modal `read-key'
-function is used instead (see `read-char-choice-with-read-key')."
+  "Read and return one of the characters in CHARS, prompting with PROMPT.
+CHARS should be a list of single characters.
+The function discards any input character that is not one of CHARS,
+and shows a message to the effect that it is not one of the expected
+charcaters.
+
+By default, use the minibuffer to read the key non-modally (see
+`read-char-from-minibuffer').  But if `read-char-choice-use-read-key'
+is non-nil, the modal `read-key' function is used instead (see
+`read-char-choice-with-read-key')."
   (if (not read-char-choice-use-read-key)
       (read-char-from-minibuffer prompt chars)
     (read-char-choice-with-read-key prompt chars inhibit-keyboard-quit)))
 
 (defun read-char-choice-with-read-key (prompt chars &optional 
inhibit-keyboard-quit)
-  "Read and return one of CHARS, prompting for PROMPT.
+  "Read and return one of the characters in CHARS, prompting with PROMPT.
+CHARS should be a list of single characters.
 Any input that is not one of CHARS is ignored.
 
 If optional argument INHIBIT-KEYBOARD-QUIT is non-nil, ignore
-`keyboard-quit' events while waiting for a valid input.
+`keyboard-quit' events while waiting for valid input.
 
 If you bind the variable `help-form' to a non-nil value
 while calling this function, then pressing `help-char'
@@ -3519,15 +3523,15 @@ Also discard all previous input in the minibuffer."
     (sit-for 2)))
 
 (defvar y-or-n-p-use-read-key nil
-  "Prefer `read-key' when answering a \"y or n\" question by `y-or-n-p'.
-Otherwise, use the minibuffer.
-
-When using the minibuffer, the user is less constrained, and can
-use the normal commands available in the minibuffer, and can, for
-instance, switch to another buffer, do things there, and then
-switch back again to the minibuffer before entering the
-character.  This is not possible when using `read-key', but using
-`read-key' may be less confusing to some users.")
+  "Use `read-key' when reading answers to \"y or n\" questions by `y-or-n-p'.
+Otherwise, use the `read-from-minibuffer' to read the answers.
+
+When reading via the minibuffer, you can use the normal commands
+available in the minibuffer, and can, for instance, temporarily
+switch to another buffer, do things there, and then switch back
+to the minibuffer before entering the character.  This is not
+possible when using `read-key', but using `read-key' may be less
+confusing to some users.")
 
 (defvar from--tty-menu-p nil
   "Non-nil means the current command was invoked from a TTY menu.")