bug#23937: 25.0.95; Search functions doc fixes/improvements

[Eli Zaretskii]

> From: Stephen Berman <stephen.berman@gmx.net>
> Cc: 23937@debbugs.gnu.org
> Date: Mon, 11 Jul 2016 23:55:19 +0200
> 
> >> @@ -2247,14 +2252,15 @@ DEFUN ("posix-search-backward", 
> >> Fposix_search_backward, Sposix_search_backward,
> >>         "sPosix search backward: ",
> >>         doc: /* Search backward from point for match for regular 
> >> expression REGEXP.
> >>  Find the longest match in accord with Posix regular expression rules.
> >> -Set point to the beginning of the match, and return point.
> >> -The match found is the one starting last in the buffer
> >> -and yet ending before the origin of the search.
> >> +Set point to the beginning of the occurrence found, and return point.
> >
> > The 2nd and 3rd lines you removed seem to provide valuable information
> > which is now gone, no?
> 
> I removed them because I thought they were (i) partly redundant: the
> first words of the doc string, "Search backward from point", already
> imply that the match ends before that position, since otherwise it
> wouldn't be a search backward

I don't agree, I think this part is not clear unless explicitly
described.  I frequently find myself wondering about this when I
need to code a loop that uses these functions.

> and (ii) partly inaccurate: saying the
> match found is the last one in the buffer before the starting point is
> only true when COUNT is 1 (or nil)

Then let's make it more accurate, but I don't think removing that is
TRT.  In particular, there's nothing wrong with describing what
happens with COUNT = 1 if the clarity is required only in that case.

> I assume it's ok to push the changes to emacs-25?

Yes.

(The comment about COUNT = 0 was a teaser, don't worry about that.)