master b295174: Clarify point position after text-property-search

[Stefan Kangas]

branch: master
commit b295174210465c4285729c67ec014e0f5b53f741
Author: Stefan Kangas <stefan@marxist.se>
Commit: Stefan Kangas <stefan@marxist.se>

    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.
---
 lisp/emacs-lisp/text-property-search.el            | 12 ++++++------
 test/lisp/emacs-lisp/text-property-search-tests.el | 18 ++++++++++++++++++
 2 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/lisp/emacs-lisp/text-property-search.el 
b/lisp/emacs-lisp/text-property-search.el
index 61bd98d..d7dc7da 100644
--- 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 83d4b95..2781550 100644
--- 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)))
 
+
+;;;; 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