Merge from origin/emacs-30

894b0e3a2fe ; Adapt comment in tramp.el
cc87717fa07 Add keyword placeholder to tramp.el
7d0d61d8549 Rewrite ERT manual introduction
b2f124f2a88 ; cperl-mode.el: Don't misinterpret exec_fcn as keyword exec
59d1aac49df Document return values of the various read-* functions

3 files changed, 9 insertions, 6 deletions

diff --git a/src/coding.c b/src/coding.c
index 4f7cf23e96e..b0bd5d3a9ab 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 d45860fd470..add8deb3954 100644
--- a/src/lread.c
+++ b/src/lread.c
@@ -855,7 +855,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
@@ -903,7 +903,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
@@ -939,7 +939,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 720172a3aa4..b0d54bd51f0 100644
--- a/src/minibuf.c
+++ b/src/minibuf.c
@@ -1296,7 +1296,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.
@@ -1448,7 +1448,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.  */)