bug#24353: 25.1.1: looking-back wrong info

[Drew Adams <drew.adams@oracle.com>]

> > The right fix is to have the doc do three things:
> >
> > 1. Be honest about the signature.
> 
> Casting this as a moral issue (about "honesty") doesn't seem to be
> constructive.  Anyway, the whole point of advertised-calling-convention
> is to advertise a signature different from the actual implemented one.

It's not about morality.  It's about the signature being 
accurate/truthful/correct.  Substitute "accurate" if that makes
it clearer.  It's not a moral question.  It's about helping users
as best we can.  What's the most helpful thing to do here?
That's the question.

And yes, "the whole point of advertised-calling-convention is to
advertise a signature different from the actual implemented one."
The question is whether that is the right thing to do _here_.

It is a tool used sparingly.  As I said at the outset, "I have a
question as to why this was changed."  I question whether _this_
change is a good one - whether this is a good case for using
`advertised-calling-convention'.

> > 2. Recommend strongly that you use LIMIT.
> > 3. Say WHY you should use LIMIT: not doing so can lead
> >    to poor performance.
> 
> The doc string already says
>     LIMIT if non-nil speeds up the search by specifying a minimum
>     starting position, to avoid checking matches that would start
>     before LIMIT.

Right.  And is that not enough?

Emacs itself uses `looking-back' without LIMIT in several places.
Presumably those are places where it should NOT (or cannot) be
used (or else they should be corrected).  Why would we assume now
that other programmers use `looking-back' without LIMIT when they
should be providing LIMIT?  IOW, where's the problem?

> > Had #2 and #3 been in the doc when you (presumably) first
> > consulted it, you would likely have included LIMIT, and
> > there would be no need to "upgrade" your code now.
> >
> > Is there a reason to avoid using `looking-back', even if
> > LIMIT is provided?  It too should be mentioned in the doc.
> 
> The docstring already says
>     As a general recommendation, try to avoid using
>     ‘looking-back’ wherever possible, since it is slow.

I know.  That's why I asked the question.  It just says that
it is slow, without reference to LIMIT.  Doesn't seem to be
as helpful as it presumably could be.

But again, are we sure that programmers are misusing the function?
Or is this perhaps another case of if-it-aint-broke-dont-fix-it?