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/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