1 files changed, 32 insertions, 30 deletions

diff --git a/lisp/emacs-lisp/text-property-search.el b/lisp/emacs-lisp/text-property-search.el
index 41ca07057e0..a589d0915b9 100644
--- a/lisp/emacs-lisp/text-property-search.el
+++ b/lisp/emacs-lisp/text-property-search.el
@@ -30,29 +30,29 @@
   beginning end value)
 
 (defun text-property-search-forward (property &optional value predicate
-                                              not-immediate)
-  "Search for the next region that has text property PROPERTY set to VALUE.
-If not found, the return value is nil.  If found, point will be
-placed at the end of the region and an object describing the
-match is returned.
-
-PREDICATE is called with two values.  The first is the VALUE
-parameter.  The second is the value of PROPERTY.  This predicate
-should return non-nil if there is a match.
-
-Some convenience values for PREDICATE can also be used.  `t'
-means the same as `equal'.  `nil' means almost the same as \"not
-equal\", but will also end the match if the value of PROPERTY
-changes.  See the manual for extensive examples.
-
-If `not-immediate', if the match is under point, it will not be
-returned, but instead the next instance is returned, if any.
-
-The return value (if a match is made) is a `prop-match'
-structure.  The accessors available are
-`prop-match-beginning'/`prop-match-end' (the region in the buffer
-that's matching), and `prop-match-value' (the value of PROPERTY
-at the start of the region)."
+                                              not-current)
+  "Search for the next region of text whose PROPERTY matches VALUE.
+
+If not found, return nil and don't move point.
+If found, move point to end of the region and return a `prop-match'
+object describing the match.  To access the details of the match,
+use `prop-match-beginning' and `prop-match-end' for the buffer
+positions that limit the region, and `prop-match-value' for the
+value of PROPERTY in the region.
+
+PREDICATE is used to decide whether a value of PROPERTY should be
+considered as matching VALUE.
+If PREDICATE is t, that means a value must `equal' VALUE to be
+considered a match.
+If PREDICATE is nil, a value will match if it is non-nil and
+is NOT `equal' to VALUE.
+If PREDICATE is a function, it will be called with two arguments:
+VALUE and the value of PROPERTY.  The function should return
+non-nil if these two values are to be considered a match.
+
+If NOT-CURRENT is non-nil, the function will search for the first
+region that doesn't include point and has a value of PROPERTY
+that matches VALUE."
   (interactive
    (list
     (let ((string (completing-read "Search for property: " obarray)))
@@ -66,13 +66,13 @@ at the start of the region)."
    ;; end.
    ((and (text-property--match-p value (get-text-property (point) property)
                                  predicate)
-         (not not-immediate))
+         (not not-current))
     (text-property--find-end-forward (point) property value predicate))
    (t
     (let ((origin (point))
           (ended nil)
           pos)
-      ;; Fix the next candidate.
+      ;; Find the next candidate.
       (while (not ended)
         (setq pos (next-single-property-change (point) property))
         (if (not pos)
@@ -121,9 +121,11 @@ at the start of the region)."
 
 
 (defun text-property-search-backward (property &optional value predicate
-                                               not-immediate)
-  "Search for the previous region that has text property PROPERTY set to VALUE.
-See `text-property-search-forward' for further documentation."
+                                               not-current)
+  "Search for the previous region of text whose PROPERTY matches VALUE.
+
+Like `text-property-search-forward', which see, but searches backward,
+and if a matching region is found, moves point to its beginning."
   (interactive
    (list
     (let ((string (completing-read "Search for property: " obarray)))
@@ -138,14 +140,14 @@ See `text-property-search-forward' for further documentation."
    ((and (text-property--match-p
           value (get-text-property (1- (point)) property)
           predicate)
-         (not not-immediate))
+         (not not-current))
     (text-property--find-end-backward (1- (point)) property value predicate))
    (t
     (let ((origin (point))
           (ended nil)
           pos)
       (forward-char -1)
-      ;; Fix the next candidate.
+      ;; Find the previous candidate.
       (while (not ended)
         (setq pos (previous-single-property-change (point) property))
         (if (not pos)