Clarify point position after text-property-search

* lisp/emacs-lisp/text-property-search.el
(text-property-search-forward, text-property-search-backward): Doc fix
to clarify placement of point after search.
* test/lisp/emacs-lisp/text-property-search-tests.el
(text-property-search--pos-test): New defun.
(text-property-search-forward-point-at-beginning)
(text-property-search-backward-point-at-end): New test.

diff --git a/lisp/emacs-lisp/text-property-search.el b/lisp/emacs-lisp/text-property-search.el
index 61bd98d3cfea4125d1c28b9156535772a528c570..d7dc7da7c18add9ad09c1f287b31aa43d3fe299e 100644 (file)
--- a/lisp/emacs-lisp/text-property-search.el
+++ b/lisp/emacs-lisp/text-property-search.el
@@ -34,11 +34,11 @@
   "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.
+If found, move point to the start 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.
@@ -125,7 +125,7 @@ that matches VALUE."
   "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."
+and if a matching region is found, place point at its end."
   (interactive
    (list
     (let ((string (completing-read "Search for property: " obarray)))

diff --git a/test/lisp/emacs-lisp/text-property-search-tests.el b/test/lisp/emacs-lisp/text-property-search-tests.el
index 83d4b95b76bcf75a306f12162f223a2c20d93d12..278155006c2558db0aceddf1a11720b55b365f5f 100644 (file)
--- a/test/lisp/emacs-lisp/text-property-search-tests.el
+++ b/test/lisp/emacs-lisp/text-property-search-tests.el
@@ -153,6 +153,24 @@
    46 57 nil
    (point-max)))
 
+\f
+;;;; Position after search.
+
+(defun text-property-search--pos-test (fun pos &optional reverse)
+  (with-temp-buffer (:name "position")
+    (insert (concat "foo "
+                  (propertize "bar" 'x t)
+                  " baz"))
+    (goto-char (if reverse (point-max) (point-min)))
+    (funcall fun 'x t)
+    (should (= (point) pos))))
+
+(ert-deftest text-property-search-forward-point-at-beginning ()
+  (text-property-search--pos-test #'text-property-search-forward 5))
+
+(ert-deftest text-property-search-backward-point-at-end ()
+  (text-property-search--pos-test #'text-property-search-backward 8 t))
+
 (provide 'text-property-search-tests)
 
 ;;; text-property-search-tests.el ends here