; Improve documentation of text-property-search-* functions

* doc/lispref/text.texi (Property Search): Improve wording and markup.

* lisp/emacs-lisp/text-property-search.el (text-property-search-forward)
(text-property-search-backward): Doc fixes.  (Bug#64367)

1 files changed, 18 insertions, 17 deletions

diff --git a/lisp/emacs-lisp/text-property-search.el b/lisp/emacs-lisp/text-property-search.el
index 920278b903a..669cdd97319 100644
--- a/lisp/emacs-lisp/text-property-search.el
+++ b/lisp/emacs-lisp/text-property-search.el
@@ -31,40 +31,41 @@
 
 (defun text-property-search-forward (property &optional value predicate
                                               not-current)
-  "Search for the next region of text where PREDICATE is true.
-PREDICATE is used to decide whether a value of PROPERTY should be
-considered as matching VALUE.
+  "Search for next region of text where PREDICATE returns non-nil for PROPERTY.
+PREDICATE is used to decide whether the value of PROPERTY at a given
+buffer position should be considered as a match for VALUE.
+VALUE defaults to nil if omitted.
 
 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.
+VALUE and the value of PROPERTY at some buffer position.  The function
+should return non-nil if these two values are to be considered a match.
 
 Two special values of PREDICATE can also be used:
-If PREDICATE is t, that means a value must `equal' VALUE to be
-considered a match.
-If PREDICATE is nil (which is the default value), a value will
-match if is not `equal' to VALUE.  Furthermore, a nil PREDICATE
-means that the match region is ended if the value changes.  For
+If PREDICATE is t, that means the value of PROPERTY must `equal' VALUE
+to be considered a match.
+If PREDICATE is nil (which is the default), the value of PROPERTY will
+match if it is not `equal' to VALUE.  Furthermore, a nil PREDICATE
+means that the match region ends where the value changes.  For
 instance, this means that if you loop with
 
   (while (setq prop (text-property-search-forward \\='face))
     ...)
 
-you will get all distinct regions with non-nil `face' values in
+you will get all the distinct regions with non-nil `face' values in
 the buffer, and the `prop' object will have the details about the
 match.  See the manual for more details and examples about how
 VALUE and PREDICATE interact.
 
-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.
+If NOT-CURRENT is non-nil, current buffer position is not examined for
+matches: the function will search for the first region that doesn't
+include point and has a value of PROPERTY that matches VALUE.
 
 If no matches can be found, return nil and don't move point.
 If found, move point to the 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."
+the buffer positions that limit the region, and `prop-match-value'
+for the value of PROPERTY in the region."
   (interactive
    (list
     (let ((string (completing-read "Search for property: " obarray)))
@@ -134,7 +135,7 @@ the buffer positions that limit the region, and
 
 (defun text-property-search-backward (property &optional value predicate
                                                not-current)
-  "Search for the previous region of text whose PROPERTY matches VALUE.
+  "Search for previous region of text where PREDICATE returns non-nil for PROPERTY.
 
 Like `text-property-search-forward', which see, but searches backward,
 and if a matching region is found, place point at the start of the region."