From 908b8123b4c8d651bb067bc058dda648e43fa1e2 Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Fri, 7 Mar 2025 18:10:53 +0100 Subject: [PATCH] Explicitly document read-string return value * src/minibuf.c (Fread_string): Document return value explicitly. Better document PROMPT argument, and reflow docstring. (Bug#76797) (cherry picked from commit af8017b23f6d94266dd05dcd084c8d7656393db8) --- src/minibuf.c | 34 +++++++++++++++++++++------------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/src/minibuf.c b/src/minibuf.c index 3f79726624a..4d1d042be70 100644 --- a/src/minibuf.c +++ b/src/minibuf.c @@ -1331,20 +1331,28 @@ and some related functions, which use zero-indexing for POSITION. */) /* Functions that use the minibuffer to read various things. */ DEFUN ("read-string", Fread_string, Sread_string, 1, 5, 0, - doc: /* Read a string from the minibuffer, prompting with string PROMPT. -If non-nil, second arg INITIAL-INPUT is a string to insert before reading. - This argument has been superseded by DEFAULT-VALUE and should normally be nil - in new code. It behaves as INITIAL-CONTENTS in `read-from-minibuffer' (which - see). -The third arg HISTORY, if non-nil, specifies a history list - and optionally the initial position in the list. + doc: /* Read and return a string from the minibuffer, prompting with PROMPT. + +PROMPT is a string, which should normally end with the string ": ". + +If non-nil, second arg INITIAL-INPUT is a string to insert before +reading. This argument has been superseded by DEFAULT-VALUE and should +normally be nil in new code. It behaves as INITIAL-CONTENTS in +`read-from-minibuffer' (which see). + +The third arg HISTORY, if non-nil, specifies a history list and +optionally the initial position in the list. + See `read-from-minibuffer' for details of HISTORY argument. -Fourth arg DEFAULT-VALUE is the default value or the list of default values. - If non-nil, it is used for history commands, and as the value (or the first - element of the list of default values) to return if the user enters the - empty string. -Fifth arg INHERIT-INPUT-METHOD, if non-nil, means the minibuffer inherits - the current input method and the setting of `enable-multibyte-characters'. */) + +Fourth arg DEFAULT-VALUE is the default value or the list of default +values. If non-nil, it is used for history commands, and as the value +(or the first element of the list of default values) to return if the +user enters the empty string. + +Fifth arg INHERIT-INPUT-METHOD, if non-nil, means the minibuffer +inherits the current input method and the setting of +`enable-multibyte-characters'. */) (Lisp_Object prompt, Lisp_Object initial_input, Lisp_Object history, Lisp_Object default_value, Lisp_Object inherit_input_method) { Lisp_Object val; -- 2.39.5