Improve documentation of 'repeat-mode' and related variables

* lisp/bindings.el (next-error-repeat-map)
(page-navigation-repeat-map, undo-repeat-map):
* lisp/tab-bar.el (tab-bar-switch-repeat-map)
(tab-bar-move-repeat-map):
* lisp/window.el (other-window-repeat-map)
(resize-window-repeat-map): Mention repeatable commands in the doc
strings.
* lisp/repeat.el (repeat-exit-timeout, repeat-check-key)
(repeat-echo-function, repeat-mode, repeat-check-key)
(repeat-check-map, repeat-echo-message-string)
(repeat-echo-message, repeat-echo-mode-line)
(describe-repeat-maps): Improve wording of doc strings.
(describe-repeat-maps): Improve wording of the heading line.
(Bug#61183)

* doc/emacs/basic.texi (Repeating): Clarify and improve wording of
'repeat-mode' documentation.

1 files changed, 30 insertions, 19 deletions

diff --git a/lisp/repeat.el b/lisp/repeat.el
index ce59b310792..37d4aaec985 100644
--- a/lisp/repeat.el
+++ b/lisp/repeat.el
@@ -349,7 +349,7 @@ For example, you can set it to <return> like `isearch-exit'."
   :version "28.1")
 
 (defcustom repeat-exit-timeout nil
-  "Break the repetition chain of keys after specified timeout.
+  "Break the repetition chain of keys after specified amount of idle time.
 When a number, exit the transient repeating mode after idle time
 of the specified number of seconds.
 You can also set the property `repeat-exit-timeout' on the command symbol.
@@ -380,12 +380,12 @@ This property can override the value of this variable."
 
 (defcustom repeat-check-key t
   "Whether to check that the last key exists in the repeat map.
-When non-nil and the last typed key (with or without modifiers)
-doesn't exist in the keymap attached by the `repeat-map' property,
-then don't activate that keymap for the next command.  So only the
-same keys among repeatable keys are allowed in the repeating sequence.
-For example, with a non-nil value, only \\`C-x u u' repeats undo,
-whereas \\`C-/ u' doesn't.
+When non-nil, and the last typed key (with or without modifiers)
+doesn't exist in the keymap specified by the `repeat-map' property
+of the command, don't activate that keymap for the next command.
+Thus, when this is non-nil, only the same keys among repeatable
+keys are allowed in the repeating sequence. For example, with a
+non-nil value, only \\`C-x u u' repeats undo, whereas \\`C-/ u' doesn't.
 
 You can also set the property `repeat-check-key' on the command symbol.
 This property can override the value of this variable.
@@ -398,7 +398,7 @@ but the property value is `t', then check the last key."
 
 (defcustom repeat-echo-function #'repeat-echo-message
   "Function to display a hint about available keys.
-Function is called after every repeatable command with one argument:
+The function is called after every repeatable command with one argument:
 a repeating map, or nil after deactivating the transient repeating mode.
 You can use `add-function' for multiple functions simultaneously."
   :type '(choice (const :tag "Show hints in the echo area"
@@ -422,8 +422,12 @@ the map can't be set on the command symbol property `repeat-map'.")
 ;;;###autoload
 (define-minor-mode repeat-mode
   "Toggle Repeat mode.
-When Repeat mode is enabled, and the command symbol has the property named
-`repeat-map', this map is activated temporarily for the next command.
+When Repeat mode is enabled, certain commands bound to multi-key
+sequences can be repeated by typing a single key, after typing the
+full key sequence once.
+The commands which can be repeated like that are those whose symbol
+ has the property `repeat-map' which specifies a keymap of single
+keys for repeating.
 See `describe-repeat-maps' for a list of all repeatable commands."
   :global t :group 'repeat
   (if (not repeat-mode)
@@ -459,7 +463,7 @@ See `describe-repeat-maps' for a list of all repeatable commands."
         rep-map))))
 
 (defun repeat-check-key (key map)
-  "Check if the last key is suitable to activate the repeating MAP."
+  "Check if the last KEY is suitable for activating the repeating MAP."
   (let* ((prop (repeat--command-property 'repeat-check-key))
          (check-key (unless (eq prop 'no) (or prop repeat-check-key))))
     (or (not check-key)
@@ -471,7 +475,7 @@ See `describe-repeat-maps' for a list of all repeatable commands."
   "Previous minibuffer state.")
 
 (defun repeat-check-map (map)
-  "Decides whether MAP can be used for the next command."
+  "Decide whether MAP can be used for the next command."
   (and map
        ;; Detect changes in the minibuffer state to allow repetitions
        ;; in the same minibuffer, but not when the minibuffer is activated
@@ -547,7 +551,7 @@ This function can be used to force exit of repetition while it's active."
     (setq repeat-exit-function nil)))
 
 (defun repeat-echo-message-string (keymap)
-  "Return a string with a list of repeating keys."
+  "Return a string with the list of repeating keys in KEYMAP."
   (let (keys)
     (map-keymap (lambda (key cmd) (and cmd (push key keys))) keymap)
     (format-message "Repeat with %s%s"
@@ -565,7 +569,8 @@ This function can be used to force exit of repetition while it's active."
                       ""))))
 
 (defun repeat-echo-message (keymap)
-  "Display available repeating keys in the echo area."
+  "Display in the echo area the repeating keys defined by KEYMAP.
+See `repeat-echo-function' to enable/disable."
   (let ((message-log-max nil))
     (if keymap
         (let ((message (repeat-echo-message-string keymap)))
@@ -586,7 +591,9 @@ This function can be used to force exit of repetition while it's active."
   "String displayed in the mode line in repeating mode.")
 
 (defun repeat-echo-mode-line (keymap)
-  "Display the repeat indicator in the mode line."
+  "Display the repeat indicator in the mode line.
+KEYMAP should be non-nil, but is otherwise ignored.
+See `repeat-echo-function' to enable/disable."
   (if keymap
       (unless (assq 'repeat-in-progress mode-line-modes)
         (add-to-list 'mode-line-modes (list 'repeat-in-progress
@@ -596,9 +603,11 @@ This function can be used to force exit of repetition while it's active."
 (declare-function help-fns--analyze-function "help-fns" (function))
 
 (defun describe-repeat-maps ()
-  "Describe mappings of commands repeatable by symbol property `repeat-map'.
-If `repeat-mode' is enabled, these keymaps determine which single key
-can be used to repeat a command invoked via a full key sequence."
+  "Describe transient keymaps installed for repeating multi-key commands.
+These keymaps enable repetition of commands bound to multi-key
+sequences by typing just one key, when `repeat-mode' is enabled.
+Commands that can be repeated this way must have their symbol
+to have the `repeat-map' property whose value specified a keymap."
   (interactive)
   (require 'help-fns)
   (let ((help-buffer-under-preparation t))
@@ -613,7 +622,9 @@ can be used to repeat a command invoked via a full key sequence."
       (with-help-window (help-buffer)
         (with-current-buffer standard-output
           (setq-local outline-regexp "[*]+")
-          (insert "A list of keymaps used by commands with the symbol property `repeat-map'.\n")
+          (insert "\
+A list of keymaps and their single-key shortcuts for repeating commands.
+Click on a keymap to see the commands repeatable by the keymap.\n")
 
           (dolist (keymap (sort keymaps (lambda (a b)
                                           (when (and (symbolp (car a))