From 59d1aac49dfdc49e34be5964f547db0cfa7e127b Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sun, 9 Mar 2025 15:02:39 +0200 Subject: [PATCH] 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 | 2 +- lisp/emacs-lisp/map-ynp.el | 3 +-- lisp/env.el | 2 +- lisp/faces.el | 6 +++--- lisp/files-x.el | 10 +++++++--- lisp/files.el | 1 + lisp/international/mule-cmds.el | 1 + lisp/international/mule-diag.el | 1 + lisp/language/japan-util.el | 3 ++- lisp/minibuffer.el | 5 +++-- lisp/replace.el | 2 +- lisp/simple.el | 11 +++++++---- lisp/subr.el | 4 ++-- lisp/textmodes/string-edit.el | 3 +++ src/coding.c | 5 ++++- src/lread.c | 6 +++--- src/minibuf.c | 4 ++-- 17 files changed, 43 insertions(+), 26 deletions(-) diff --git a/lisp/auth-source.el b/lisp/auth-source.el index d22747493b2..c72cb24cf74 100644 --- a/lisp/auth-source.el +++ b/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. diff --git a/lisp/emacs-lisp/map-ynp.el b/lisp/emacs-lisp/map-ynp.el index 2d24f783958..5b9ffe3a03d 100644 --- a/lisp/emacs-lisp/map-ynp.el +++ b/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 diff --git a/lisp/env.el b/lisp/env.el index 288f7e224d7..9e8b7f53a11 100644 --- a/lisp/env.el +++ b/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 diff --git a/lisp/faces.el b/lisp/faces.el index 01800c4c105..bbd6bf06d03 100644 --- a/lisp/faces.el +++ b/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 diff --git a/lisp/files-x.el b/lisp/files-x.el index cdc38508c5a..82b69de7c17 100644 --- a/lisp/files-x.el +++ 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))) diff --git a/lisp/files.el b/lisp/files.el index 380721f1fe2..007fd23a5f5 100644 --- a/lisp/files.el +++ b/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.) diff --git a/lisp/international/mule-cmds.el b/lisp/international/mule-cmds.el index 4d153ea91db..24ae65c1145 100644 --- a/lisp/international/mule-cmds.el +++ b/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. diff --git a/lisp/international/mule-diag.el b/lisp/international/mule-diag.el index 03376e876bf..44d20e39507 100644 --- a/lisp/international/mule-diag.el +++ b/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. diff --git a/lisp/language/japan-util.el b/lisp/language/japan-util.el index c61e98c8fca..718c469d562 100644 --- a/lisp/language/japan-util.el +++ b/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")) ;; diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el index cfce7de8df1..f0db98cdc1d 100644 --- a/lisp/minibuffer.el +++ b/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. diff --git a/lisp/replace.el b/lisp/replace.el index e17514215ef..beecc78c437 100644 --- a/lisp/replace.el +++ b/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 diff --git a/lisp/simple.el b/lisp/simple.el index 152a8c451ac..e1f6ae8b683 100644 --- a/lisp/simple.el +++ b/lisp/simple.el @@ -2275,7 +2275,7 @@ This is used by the \\\\[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) diff --git a/lisp/subr.el b/lisp/subr.el index 37a3f9efe6b..42706397674 100644 --- a/lisp/subr.el +++ b/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' diff --git a/lisp/textmodes/string-edit.el b/lisp/textmodes/string-edit.el index 1188a965f6f..3c76db202c7 100644 --- a/lisp/textmodes/string-edit.el +++ b/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 diff --git a/src/coding.c b/src/coding.c index b8ed3a35957..619a362d328 100644 --- a/src/coding.c +++ b/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) diff --git a/src/lread.c b/src/lread.c index 1d41a9d5cf4..6610f82d927 100644 --- a/src/lread.c +++ b/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 diff --git a/src/minibuf.c b/src/minibuf.c index 026a8f4271e..3cb7ff47030 100644 --- a/src/minibuf.c +++ b/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. */)