; Improve and correct documentation of registers (bug#66394)

Suggested by Thierry Volpiatto <thievol@posteo.net>.
* doc/emacs/regs.texi (Registers): Mention filtering of registers
in the preview.

* lisp/register.el (register-use-preview)
(register--preview-function, register-preview-info): Doc fixes.

2 files changed, 12 insertions, 8 deletions

diff --git a/doc/emacs/regs.texi b/doc/emacs/regs.texi
index d7542e996dc..988e606741f 100644
--- a/doc/emacs/regs.texi
+++ b/doc/emacs/regs.texi
@@ -65,9 +65,16 @@ the registers in the preview window.  To overwrite the value of an
 existing registers in this mode, you need to type @key{RET} after
 selecting the register by navigation or typing its name.
 
+In addition, the registers shown by the preview are filtered according
+to the command that popped the preview: for example, the preview shown
+by @code{insert-register} will only show registers whose values can be
+inserted into the buffer, omitting registers which hold window
+configurations, positions, and other un-insertable values.
+
 @item nil
 This value requests behavior similar to @code{traditional}, but the
-preview is shown without delay.
+preview is shown without delay, and is filtered according to the
+command.
 
 @item never
 This value is like @code{nil}, but it disables the preview.
diff --git a/lisp/register.el b/lisp/register.el
index bd8e8c2edcd..d1d55dff660 100644
--- a/lisp/register.el
+++ b/lisp/register.el
@@ -138,10 +138,7 @@ When set to \\='never, behave as with nil, but with no preview buffer at
 all; the preview buffer is still accessible with `help-char' (C-h).
 When set to \\='traditional (the default), provide a more basic preview
 according to `register-preview-delay'; this preserves the traditional
-behavior of Emacs 29 and before.
-
-This has no effect when the value of `register--read-with-preview-function'
-is `register-read-with-preview-traditional'."
+behavior of Emacs 29 and before."
   :type '(choice
           (const :tag "Use preview" t)
           (const :tag "Use quick preview" nil)
@@ -192,8 +189,7 @@ and is used when `register-use-preview' is set to \\='traditional."
           (register-describe-oneline (car r))))
 
 (cl-defgeneric register--preview-function (read-preview-function)
-  "Return a function to format a register for previewing.
-This is according to the value of `read-preview-function'.")
+  "Return a function to format registers for previewing by READ-PREVIEW-FUNCTION.")
 (cl-defmethod register--preview-function ((_read-preview-function
                                            (eql register-read-with-preview-traditional)))
   #'register-preview-default)
@@ -207,7 +203,8 @@ TYPES are the supported types of registers.
 MSG is the minibuffer message to show when a register is selected.
 ACT is the type of action the command is doing on register.
 SMATCH accept a boolean value to say if the command accepts non-matching
-registers."
+registers.
+If NOCONFIRM is non-nil, request confirmation of register name by RET."
   types msg act smatch noconfirm)
 
 (cl-defgeneric register-command-info (command)