; Improve documentation of lazy-highlight in search and replace commands

* lisp/isearch.el (lazy-highlight, lazy-highlight-initial-delay)
(lazy-highlight-buffer, isearch-lazy-highlight, isearch-forward):
* lisp/replace.el (query-replace, query-replace-lazy-highlight)
(query-replace, query-replace-regexp): Doc fixes.

* doc/emacs/search.texi (Search Customizations): Document
'lazy-highlight-buffer' and 'lazy-highlight-buffer-max-at-a-time'.
Use @vtable to avoid the need of indexing each variable
separately.

2 files changed, 32 insertions, 8 deletions

diff --git a/lisp/isearch.el b/lisp/isearch.el
index 785d324cac3..92bd9af6643 100644
--- a/lisp/isearch.el
+++ b/lisp/isearch.el
@@ -347,6 +347,9 @@ you can define more of these faces using the same numbering scheme."
 When non-nil, all text currently visible on the screen
 matching the current search string is highlighted lazily
 (see `lazy-highlight-initial-delay' and `lazy-highlight-interval').
+However, if `lazy-highlight-buffer' is non-nil, all text in the
+entire buffer matching the search string is highlighted lazily.
+The highlighting uses the `lazy-highlight' face.
 
 When multiple windows display the current buffer, the
 highlighting is displayed only on the selected window, unless
@@ -385,8 +388,8 @@ If this is nil, extra highlighting can be \"manually\" removed with
 
 (defcustom lazy-highlight-initial-delay 0.25
   "Seconds to wait before beginning to lazily highlight all matches.
-This setting only has effect when the search string is less than
-`lazy-highlight-no-delay-length' characters long."
+This setting only has effect when the search string is shorter than
+`lazy-highlight-no-delay-length' characters."
   :type 'number
   :group 'lazy-highlight)
 
@@ -428,7 +431,9 @@ When non-nil, all text in the buffer matching the current search
 string is highlighted lazily (see `lazy-highlight-initial-delay',
 `lazy-highlight-interval' and `lazy-highlight-buffer-max-at-a-time').
 This is useful when `lazy-highlight-cleanup' is customized to nil
-and doesn't remove full-buffer highlighting after a search."
+and doesn't remove full-buffer highlighting after a search.
+If this is nil (the default), only the text currently visible in
+the window is highlighted, subject to `isearch-lazy-highlight'."
   :type 'boolean
   :group 'lazy-highlight
   :version "27.1")
@@ -443,7 +448,9 @@ and doesn't remove full-buffer highlighting after a search."
     (((class color) (min-colors 8))
      (:background "turquoise3" :distant-foreground "white"))
     (t (:underline t)))
-  "Face for lazy highlighting of matches other than the current one."
+  "Face for lazy highlighting of matches other than the current one.
+Used in Isearch when `isearch-lazy-highlight' is non-nil,
+and in `query-replace' when `query-replace-lazy-highlight' is non-nil."
   :group 'lazy-highlight
   :group 'basic-faces)
 
@@ -1006,6 +1013,9 @@ Each element is an `isearch--state' struct where the slots are
 With a prefix argument, do an incremental regular expression search instead.
 \\<isearch-mode-map>
 As you type characters, they add to the search string and are found.
+Current match for the search string is highlighted using the `isearch' face,
+and if `isearch-lazy-highlight' is non-nil, the other matches are
+highlighted using the `lazy-highlight' face.
 The following non-printing keys are bound in `isearch-mode-map'.
 
 Type \\[isearch-delete-char] to cancel last input item from end of search string.
diff --git a/lisp/replace.el b/lisp/replace.el
index 933249d824c..48e158de531 100644
--- a/lisp/replace.el
+++ b/lisp/replace.el
@@ -133,9 +133,11 @@ you can define more of these faces using the same numbering scheme."
 
 (defcustom query-replace-lazy-highlight t
   "Controls the lazy-highlighting during query replacements.
-When non-nil, all text in the buffer matching the current match
-is highlighted lazily using isearch lazy highlighting (see
-`lazy-highlight-initial-delay' and `lazy-highlight-interval')."
+When non-nil, all text matching the current match that is
+currently visible in the window is highlighted lazily using
+isearch lazy highlighting (see `lazy-highlight-initial-delay'
+and `lazy-highlight-interval').  Uses the `lazy-highlight' face
+to highlight matching text."
   :type 'boolean
   :group 'lazy-highlight
   :group 'matching
@@ -143,7 +145,9 @@ is highlighted lazily using isearch lazy highlighting (see
 
 (defface query-replace
   '((t (:inherit isearch)))
-  "Face for highlighting query replacement matches."
+  "Face for highlighting query replacement matches.
+Used in `query-replace' and `query-replace-regexp'
+when `query-replace-highlight' is non-nil"
   :group 'matching
   :version "22.1")
 
@@ -427,6 +431,11 @@ In Transient Mark mode, if the mark is active, operate on the contents
 of the region.  Otherwise, operate from point to the end of the buffer's
 accessible portion.
 
+The current match of FROM-STRING is highlighted using
+the `query-replace' face.  Other matches of FROM-STRING are highlighted
+using the `lazy-highlight' face if `query-replace-lazy-highlight' is
+non-nil.
+
 In interactive use, the prefix arg (non-nil DELIMITED in
 non-interactive use), means replace only matches surrounded by
 word boundaries.  A negative prefix arg means replace backward.
@@ -508,6 +517,11 @@ accessible portion.
 When invoked interactively, matching a newline with `\\n' will not work;
 use \\`C-q C-j' instead.  To match a tab character (`\\t'), just press \\`TAB'.
 
+The current match of REGEXP is highlighted using
+the `query-replace' face.  Other matches of REGEXP are highlighted
+using the `lazy-highlight' face if `query-replace-lazy-highlight' is
+non-nil.
+
 Use \\<minibuffer-local-map>\\[next-history-element] \
 to pull the last incremental search regexp to the minibuffer
 that reads REGEXP, or invoke replacements from