bug#31584: 27.0.50; Document again what match re-search-backward finds

[Noam Postavsky]

Michael Heerdegen <michael_heerdegen@web.de> writes:

>> (with-temp-buffer
>>   (insert "xxxxyyyy")
>>   (and (re-search-backward "x+y*" nil t)
>>        (match-string 0))) ;=> "xyyyy"
>>
>> Non-greedy wouldn't match any "y"s.  It's a bit tricky to explain both
>> correctly and clearly...
>
> Ok, good example.  You convinced me that the sentence we once had was
> actually quite good.

Actually, the manual has a pretty good explanation, maybe we can just
link to it:

>From 8caeb0df40fc1cc34cd165d68238216198e01169 Mon Sep 17 00:00:00 2001
From: Noam Postavsky <npostavs@gmail.com>
Date: Thu, 24 May 2018 19:49:11 -0400
Subject: [PATCH v1] Note caveat for backward regexp searching in docstring
 (Bug#31584)

* src/search.c (Fre_search_backward): Emphasize that backwards
searches may give shorter than expected matches.
* doc/lispref/searching.texi (Regexp Search): Add an anchor for
re-search-backward to reference.
---
 doc/lispref/searching.texi | 2 ++
 src/search.c               | 5 ++++-
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi
index fca877117d..6c1ebb22b5 100644
--- a/doc/lispref/searching.texi
+++ b/doc/lispref/searching.texi
@@ -1102,6 +1102,8 @@ Regexp Search
 @end example
 @end deffn
 
+@c This anchor is referenced by re-search-backward's docstring.
+@anchor{re-search-backward}
 @deffn Command re-search-backward regexp &optional limit noerror count
 This function searches backward in the current buffer for a string of
 text that is matched by the regular expression @var{regexp}, leaving
diff --git a/src/search.c b/src/search.c
index 842e9309a2..0600e1a4e3 100644
--- a/src/search.c
+++ b/src/search.c
@@ -2233,8 +2233,11 @@ DEFUN ("re-search-backward", Fre_search_backward, 
Sre_search_backward, 1, 4,
 This function is almost identical to `re-search-forward', except that
 by default it searches backward instead of forward, and the sign of
 COUNT also indicates exactly the opposite searching direction.
+See `re-search-forward' for details.
 
-See `re-search-forward' for details.  */)
+Note that searching backwards may give a shorter match than expected,
+because the matching still happens in the forward direction.  See Info
+anchor `(elisp) re-search-backward' for details.  */)
   (Lisp_Object regexp, Lisp_Object bound, Lisp_Object noerror, Lisp_Object 
count)
 {
   return search_command (regexp, bound, noerror, count, -1, 1, 0);
-- 
2.11.0