bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

[Eli Zaretskii]

> From: Juanma Barranquero <lekktu@gmail.com>
> Date: Mon, 23 Sep 2019 09:30:20 +0200
> Cc: Lars Ingebrigtsen <larsi@gnus.org>, 37488-done@debbugs.gnu.org
> 
> I've fixed it using NOT-CURRENT, which seems marginally clearer.

Thanks.

I had more problems with these doc strings, so I rewrote them.  Please
take a look.

I have a couple of questions regarding the documentation, which I
couldn't easily figure out.  Please help me understand them and
improve the documentation further:

 . The original doc string said about nil as PREDICATE:

     `nil' means almost the same as \"not equal\", but will also
     end the match if the value of PROPERTY changes.

   What does it mean to "end the match if the value changes"?  The
   text went on to say "See the manual for extensive examples", but
   the manual doesn't mention this aspect of nil, it just says "not
   equal".

 . The doc string stated:

     If NOT-CURRENT, if the match is under point, it will not be
     returned, but instead the next instance is returned, if any.

   But the code, AFAIU, just checks whether the value of PROPERTY at
   point matches that of the found region, which doesn't necessarily
   mean point is part of the region, it could just mean there are two
   regions with matching values of PROPERTY, and point belongs to one
   of them.  Right?

 . What is the reason for having VALUE an optional argument?  Is it a
   frequent/useful operation to look for a VALUE of nil?