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

[Eric Abrahamsen <eric@ericabrahamsen.net>]

On 05/24/18 18:14 PM, Noam Postavsky wrote:
> The docstring should definitely be clarified, but technically it can
> still be answered, if you read very carefully:

If reading the documentation takes only a little less effort than
reading the code...

>> I've been bitten by this before. I'm sure the sentence you cite is,
>> correct, but I would suggest something more explicit about backwards
>> searches. The most useful thing I could have read when I was wondering
>> why this didn't work would be something like: "re-search-backward always
>> behaves "non-greedily", i.e., it will find the shortest match before
>> point".
>
> It is greedy:
>
> (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...

Yeah, my wording is bad. I think an example might be most clear. Maybe:

#+BEGIN_SRC elisp
  (with-temp-buffer
    (let ((re "x+y+"))
     (insert "xxxxyyyy")
     (goto-char (point-min))
     (re-search-forward re nil t)
     (match-string 0) => "xxxxyyyy"
     (goto-char (point-max))
     (re-search-backward re nil t)
     (match-string 0))) => "xyyyy"
#+END_SRC

Or if there's something more concise...