From: Eli Zaretskii <eliz@gnu.org>
Date: Mon, 21 Jan 2019 16:20:33 +0000 (+0200)
Subject: Improve documentation of 'isearch-filter-predicate'
X-Git-Tag: emacs-26.1.92~51
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=928d342c81c4d442e3125ddc463d141029d6898f;p=emacs.git

Improve documentation of 'isearch-filter-predicate'

* lisp/isearch.el (isearch-filter-predicate)
(isearch-filter-visible): Doc fixes.  (Bug#34150)
---

diff --git a/lisp/isearch.el b/lisp/isearch.el
index 7ee71b4979d..25d6ad591eb 100644
--- a/lisp/isearch.el
+++ b/lisp/isearch.el
@@ -188,11 +188,14 @@ or to the end of the buffer for a backward search.")
 to the search status stack.")
 
 (defvar isearch-filter-predicate #'isearch-filter-visible
-  "Predicate that filters the search hits that would normally be available.
-Search hits that dissatisfy the predicate are skipped.  The function
-has two arguments: the positions of start and end of text matched by
-the search.  If this function returns nil, continue searching without
-stopping at this match.
+  "Predicate to filter hits of Isearch and replace commands.
+Isearch hits that don't satisfy the predicate will be skipped.
+The value should be a function of two arguments; it will be
+called with the the positions of the start and the end of the
+text matched by Isearch and replace commands.  If this function
+returns nil, Isearch and replace commands will continue searching
+without stopping at resp. replacing this match.
+
 If you use `add-function' to modify this variable, you can use the
 `isearch-message-prefix' advice property to specify the prefix string
 displayed in the search message.")
@@ -3009,10 +3012,13 @@ Optional third argument, if t, means if fail just return nil (no error).
 	      (setq isearch-hidden t)))))))
 
 (defun isearch-filter-visible (beg end)
-  "Test whether the current search hit is visible at least partially.
-Return non-nil if the text from BEG to END is visible to Isearch as
-determined by `isearch-range-invisible' unless invisible text can be
-searched too when `search-invisible' is t."
+  "Return non-nil if text between BEG and END is deemed visible by Isearch.
+This function is intended to be used as `isearch-filter-predicate'.
+It returns non-nil if the text between BEG and END is visible to
+Isearch, at least partially, as determined by `isearch-range-invisible'.
+If `search-invisible' is t, which allows Isearch matches inside
+invisible text, this function will always return non-nil, regardless
+of what `isearch-range-invisible' says."
   (or (eq search-invisible t)
       (not (isearch-range-invisible beg end))))