From df05c26df3897108619237d359260ed9c91e3d78 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 28 Sep 2019 17:43:15 +0300 Subject: [PATCH] More improvements of doc strings in text-property-search.el * lisp/emacs-lisp/text-property-search.el (text-property-search-forward) (text-property-search-backward): Further improvements of doc strings. (Bug#37488) --- lisp/emacs-lisp/text-property-search.el | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/lisp/emacs-lisp/text-property-search.el b/lisp/emacs-lisp/text-property-search.el index 24d11be21dc..a589d0915b9 100644 --- a/lisp/emacs-lisp/text-property-search.el +++ b/lisp/emacs-lisp/text-property-search.el @@ -33,24 +33,26 @@ not-current) "Search for the next region of text whose PROPERTY matches VALUE. -If not found, return nil. 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 +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 NOT `equal' to -VALUE, and will also end the match if the value of PROPERTY changes. +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 should be considered a match. +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 with matching value of PROPERTY that doesn't include point." +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))) @@ -70,7 +72,7 @@ region with matching value of PROPERTY that doesn't include point." (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) @@ -122,7 +124,8 @@ region with matching value of PROPERTY that doesn't include point." not-current) "Search for the previous region of text whose PROPERTY matches VALUE. -Like `text-property-search-forward', which see, but searches backward." +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))) @@ -144,7 +147,7 @@ Like `text-property-search-forward', which see, but searches backward." (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) -- 2.39.2