Document return values of the various read-* functions

* lisp/textmodes/string-edit.el (read-string-from-buffer):
* lisp/simple.el (read-from-kill-ring, read-shell-command)
(read-signal-name):
* lisp/replace.el (read-regexp-case-fold-search):
* lisp/auth-source.el (read-passwd):
* lisp/subr.el (read-key, read-number):
* lisp/minibuffer.el (read-file-name, read-no-blanks-input):
* lisp/international/mule-cmds.el (read-multilingual-string):
* lisp/language/japan-util.el (read-hiragana-string):
* lisp/files-x.el (read-file-local-variable)
(read-file-local-variable-mode, read-file-local-variable-value):
* lisp/faces.el (read-face-font, read-face-name):
* lisp/simple.el (read-extended-command):
* lisp/env.el (read-envvar-name):
* lisp/files.el (read-directory-name):
* lisp/faces.el (read-color):
* lisp/international/mule-diag.el (read-charset):
* lisp/emacs-lisp/map-ynp.el (read-answer):
* src/coding.c (Fread_coding_system)
(Fread_non_nil_coding_system):
* src/minibuf.c (Fread_command, Fread_from_minibuffer):
* src/lread.c (Fread_char, Fread_char_exclusive, Fread_event): Doc
fixes.

lisp/auth-source.el

@@ -2551,7 +2551,7 @@ Adapt also mode line."
 
 ;;;###autoload
 (defun read-passwd (prompt &optional confirm default)
-  "Read a password, prompting with PROMPT, and return it.
+  "Read a password, prompting with PROMPT, and return password as a string.
 If optional CONFIRM is non-nil, read the password twice to make sure.
 Optional DEFAULT is a default password to use instead of empty input.
 

lisp/emacs-lisp/map-ynp.el

@@ -312,6 +312,7 @@ variable."
 (defun read-answer (question answers)
   "Read an answer either as a complete word or its character abbreviation.
 Ask user a question and accept an answer from the list of possible answers.
+Return the long answer even when accepting short ones.
 
 QUESTION should end in a space; this function adds a list of answers to it.
 
@@ -335,8 +336,6 @@ Example:
 
 When `read-answer-short' is non-nil, accept short answers.
 
-Return a long answer even in case of accepting short ones.
-
 When `use-dialog-box' is t, pop up a dialog window to get user input."
   (let* ((short (if (eq read-answer-short 'auto)
                     (or use-short-answers

lisp/env.el

@@ -38,7 +38,7 @@
 (defvar read-envvar-name-history nil)
 
 (defun read-envvar-name (prompt &optional mustmatch)
-  "Read environment variable name, prompting with PROMPT.
+  "Read and return an environment variable name string, prompting with PROMPT.
 Optional second arg MUSTMATCH, if non-nil, means require existing envvar name.
 If it is also not t, RET does not exit if it does non-null completion."
   (completing-read prompt

lisp/faces.el

@@ -1102,7 +1102,7 @@ of the default face.  Value is FACE."
   "Text string to display as the sample text for `read-face-name'.")
 
 (defun read-face-name (prompt &optional default multiple)
-  "Read one or more face names, prompting with PROMPT.
+  "Read and return one or more face names, strings, prompting with PROMPT.
 PROMPT should not end in a space or a colon.
 
 If DEFAULT is non-nil, it should be a face (a symbol) or a face
@@ -1382,7 +1382,7 @@ of a global face.  Value is the new attribute value."
 		  (pattern &optional face frame maximum width))
 
 (defun read-face-font (face &optional frame)
-  "Read the name of a font for FACE on FRAME.
+  "Read and return the string name of the font for FACE on FRAME.
 If optional argument FRAME is nil or omitted, use the selected frame."
   (let ((completion-ignore-case t))
     (completing-read (format-message
@@ -1990,7 +1990,7 @@ If omitted or nil, that stands for the selected frame's display."
 
 (defun read-color (&optional prompt convert-to-RGB allow-empty-name msg
 			     foreground face)
-  "Read a color name or RGB triplet.
+  "Read a color name or RGB triplet, return a string, the color name or RGB.
 Completion is available for color names, but not for RGB triplets.
 
 RGB triplets have the form \"#RRGGBB\".  Each of the R, G, and B

lisp/files-x.el

@@ -38,7 +38,9 @@
 ;;; Commands to add/delete file-local/directory-local variables.
 
 (defun read-file-local-variable (prompt)
-  "Read file-local variable using PROMPT and completion.
+  "Read the name of a file-local variable using PROMPT and completion.
+Return the symbol of the variable, or nil if the user entered empty or
+null name.
 Intended to be used in the `interactive' spec of
 `add-file-local-variable', `delete-file-local-variable',
 `add-dir-local-variable', `delete-dir-local-variable'."
@@ -57,7 +59,7 @@ Intended to be used in the `interactive' spec of
     (and (stringp variable) (intern variable))))
 
 (defun read-file-local-variable-value (variable)
-  "Read value of file-local VARIABLE using completion.
+  "Read and return the value of a file-local VARIABLE using completion.
 Intended to be used in the `interactive' spec of
 `add-file-local-variable' and `add-dir-local-variable'."
   (cond
@@ -90,7 +92,9 @@ Intended to be used in the `interactive' spec of
 			    default)))))
 
 (defun read-file-local-variable-mode ()
-  "Read per-directory file-local variable's mode using completion.
+  "Read the name of a per-directory file-local variable's mode using completion.
+Return the symbol of the variable, or nil if the user entered empty or
+null name.
 Intended to be used in the `interactive' spec of
 `add-dir-local-variable', `delete-dir-local-variable'."
   (let* ((default (and (symbolp major-mode) (symbol-name major-mode)))

lisp/files.el

@@ -885,6 +885,7 @@ Default name to DEFAULT-DIRNAME if user exits with the same
 non-empty string that was inserted by this function.
  (If DEFAULT-DIRNAME is omitted, DIR combined with INITIAL is used,
   or just DIR if INITIAL is nil.)
+Return the directory as a string.
 If the user exits with an empty minibuffer, this function returns
 an empty string.  (This can happen only if the user erased the
 pre-inserted contents or if `insert-default-directory' is nil.)

lisp/international/mule-cmds.el

@@ -1676,6 +1676,7 @@ This is a subroutine for `describe-input-method'."
 
 (defun read-multilingual-string (prompt &optional initial-input input-method)
   "Read a multilingual string from minibuffer, prompting with string PROMPT.
+Return the string thus read.
 The input method selected last time is activated in minibuffer.
 If optional second argument INITIAL-INPUT is non-nil, insert it in the
 minibuffer initially.

lisp/international/mule-diag.el

@@ -206,6 +206,7 @@ Character sets for defining other charsets, or for backward compatibility
 (defun read-charset (prompt &optional default-value initial-input)
   "Read a character set from the minibuffer, prompting with string PROMPT.
 It must be an Emacs character set listed in the variable `charset-list'.
+Return the charset as a symbol.
 
 Optional arguments are DEFAULT-VALUE and INITIAL-INPUT.
 DEFAULT-VALUE, if non-nil, is the default value.

lisp/language/japan-util.el

@@ -317,7 +317,8 @@ Optional argument KATAKANA-ONLY non-nil means to convert only KATAKANA char."
 ;;;###autoload
 (defun read-hiragana-string (prompt &optional initial-input)
   "Read a Hiragana string from the minibuffer, prompting with string PROMPT.
-If non-nil, second arg INITIAL-INPUT is a string to insert before reading."
+If non-nil, second arg INITIAL-INPUT is a string to insert before reading.
+Return the string read from the minibuffer."
   (read-multilingual-string prompt initial-input "japanese-hiragana"))
 
 ;;

lisp/minibuffer.el

@@ -3091,7 +3091,7 @@ with `minibuffer-local-must-match-map'."
   "?"   #'self-insert-and-exit)
 
 (defun read-no-blanks-input (prompt &optional initial inherit-input-method)
-  "Read a string from the terminal, not allowing blanks.
+  "Read and return a string from the terminal, not allowing blanks.
 Prompt with PROMPT.  Whitespace terminates the input.  If INITIAL is
 non-nil, it should be a string, which is used as initial input, with
 point positioned at the end, so that SPACE will accept the input.
@@ -3473,7 +3473,8 @@ like the `beginning-of-buffer' command."
      (if (listp default) default (list default)))))
 
 (defun read-file-name (prompt &optional dir default-filename mustmatch initial predicate)
-  "Read file name, prompting with PROMPT and completing in directory DIR.
+  "Read a file name, prompting with PROMPT and completing in directory DIR.
+Retrun the file name as a string.
 The return value is not expanded---you must call `expand-file-name'
 yourself.
 

lisp/replace.el

@@ -929,7 +929,7 @@ regexp from the user."
       (or result input))))
 
 (defun read-regexp-case-fold-search (regexp)
-  "Return a value for `case-fold-search' based on REGEXP and current settings.
+  "Return the value for `case-fold-search' based on REGEXP and current settings.
 REGEXP is a string as returned by `read-regexp'."
   (let ((fold (get-text-property 0 'case-fold regexp)))
     (cond

lisp/simple.el

@@ -2275,7 +2275,7 @@ This is used by the \\<minibuffer-local-must-match-map>\\[execute-extended-comma
   "Minor mode used for completion in `read-extended-command'.")
 
 (defun read-extended-command (&optional prompt)
-  "Read command name to invoke via `execute-extended-command'.
+  "Read and return name of command to invoke via `execute-extended-command'.
 Use `read-extended-command-predicate' to determine which commands
 to include among completion candidates.
 
@@ -4311,7 +4311,7 @@ after the default value."
   "Keymap used for completing shell commands in minibuffer.")
 
 (defun read-shell-command (prompt &optional initial-contents hist &rest args)
-  "Read a shell command from the minibuffer.
+  "Read a shell command from the minibuffer, and return it as a string.
 The arguments are the same as the ones of `read-from-minibuffer',
 except READ and KEYMAP are missing and HIST defaults
 to `shell-command-history'."
@@ -6431,7 +6431,8 @@ variable to determine how strings should be escaped."
 (defvar read-from-kill-ring-history)
 (defun read-from-kill-ring (prompt)
   "Read a `kill-ring' entry using completion and minibuffer history.
-PROMPT is a string to prompt with."
+PROMPT is a string to prompt with.
+Return the entry as a string."
   ;; `current-kill' updates `kill-ring' with a possible interprogram-paste
   (current-kill 0)
   (let* ((history-add-new-input nil)
@@ -11193,7 +11194,9 @@ killed."
   (string= string ""))
 
 (defun read-signal-name ()
-  "Read a signal number or name."
+  "Read a signal number or name.
+Return the signal number, if the user entered a number, otherwise
+the signal symbol."
   (let ((value
          (completing-read "Signal code or name: "
                           (signal-names)

lisp/subr.el

@@ -3309,7 +3309,7 @@ miscellaneous values associated with the process."
 (defvar read-key-delay 0.01) ;Fast enough for 100Hz repeat rate, hopefully.
 
 (defun read-key (&optional prompt disable-fallbacks)
-  "Read a key from the keyboard.
+  "Read a key from the keyboard, return the event thus read.
 Contrary to `read-event' this will not return a raw event but instead will
 obey the input decoding and translations usually done by `read-key-sequence'.
 So escape sequences and keyboard encoding are taken into account.
@@ -3423,7 +3423,7 @@ with Emacs.  Do not call it directly in your own packages."
   "The default history for the `read-number' function.")
 
 (defun read-number (prompt &optional default hist)
-  "Read a numeric value in the minibuffer, prompting with PROMPT.
+  "Read from the minibuffer and return a numeric value, prompting with PROMPT.
 DEFAULT specifies a default value to return if the user just types RET.
 For historical reasons, the value of DEFAULT is always inserted into
 PROMPT, so it's recommended to use `format' instead of `format-prompt'

lisp/textmodes/string-edit.el

@@ -92,6 +92,9 @@ PROMPT will be inserted at the start of the buffer, but won't be
 included in the resulting string.  If nil, no prompt will be
 inserted in the buffer.
 
+When the user exits recursive edit, this function returns the
+edited STRING.
+
 Also see `string-edit'."
   (string-edit
    prompt

src/coding.c

@@ -8625,7 +8625,8 @@ about coding-system objects.  */)
 
 DEFUN ("read-non-nil-coding-system", Fread_non_nil_coding_system,
        Sread_non_nil_coding_system, 1, 1, 0,
-       doc: /* Read a coding system from the minibuffer, prompting with string PROMPT.  */)
+       doc: /* Read a coding system from the minibuffer, prompting with string PROMPT.
+Return the symbol of the coding-system.  */)
   (Lisp_Object prompt)
 {
   Lisp_Object val;
@@ -8641,6 +8642,8 @@ DEFUN ("read-non-nil-coding-system", Fread_non_nil_coding_system,
 DEFUN ("read-coding-system", Fread_coding_system, Sread_coding_system, 1, 2, 0,
        doc: /* Read a coding system from the minibuffer, prompting with string PROMPT.
 If the user enters null input, return second argument DEFAULT-CODING-SYSTEM.
+Return the coding-system's symbol, or nil if both the user input and
+DEFAULT-CODING-SYSTEM are empty or null.
 Ignores case when completing coding systems (all Emacs coding systems
 are lower-case).  */)
   (Lisp_Object prompt, Lisp_Object default_coding_system)

src/lread.c

@@ -859,7 +859,7 @@ read_filtered_event (bool no_switch_frame, bool ascii_required,
 
 DEFUN ("read-char", Fread_char, Sread_char, 0, 3, 0,
        doc: /* Read a character event from the command input (keyboard or macro).
-It is returned as a number.
+Return the character as a number.
 If the event has modifiers, they are resolved and reflected in the
 returned character code if possible (e.g. C-SPC yields 0 and C-a yields 97).
 If some of the modifiers cannot be reflected in the character code, the
@@ -907,7 +907,7 @@ If `inhibit-interaction' is non-nil, this function will signal an
 }
 
 DEFUN ("read-event", Fread_event, Sread_event, 0, 3, 0,
-       doc: /* Read an event object from the input stream.
+       doc: /* Read and return an event object from the input stream.
 
 If you want to read non-character events, consider calling `read-key'
 instead.  `read-key' will decode events via `input-decode-map' that
@@ -943,7 +943,7 @@ If `inhibit-interaction' is non-nil, this function will signal an
 
 DEFUN ("read-char-exclusive", Fread_char_exclusive, Sread_char_exclusive, 0, 3, 0,
        doc: /* Read a character event from the command input (keyboard or macro).
-It is returned as a number.  Non-character events are ignored.
+Return the character as a number.  Non-character events are ignored.
 If the event has modifiers, they are resolved and reflected in the
 returned character code if possible (e.g. C-SPC yields 0 and C-a yields 97).
 If some of the modifiers cannot be reflected in the character code, the

src/minibuf.c

@@ -1292,7 +1292,7 @@ barf_if_interaction_inhibited (void)
 
 DEFUN ("read-from-minibuffer", Fread_from_minibuffer,
        Sread_from_minibuffer, 1, 7, 0,
-       doc: /* Read a string from the minibuffer, prompting with string PROMPT.
+       doc: /* Read and return a string from the minibuffer, prompting with string PROMPT.
 The optional second arg INITIAL-CONTENTS is an obsolete alternative to
   DEFAULT-VALUE.  It normally should be nil in new code, except when
   HIST is a cons.  It is discussed in more detail below.
@@ -1444,7 +1444,7 @@ inherits the current input method and the setting of
 }
 
 DEFUN ("read-command", Fread_command, Sread_command, 1, 2, 0,
-       doc: /* Read the name of a command and return as a symbol.
+       doc: /* Read the name of a command and return it as a symbol.
 Prompt with PROMPT.  By default, return DEFAULT-VALUE or its first element
 if it is a list.  If DEFAULT-VALUE is omitted or nil, and the user enters
 null input, return a symbol whose name is an empty string.  */)