bug#24353: 25.1.1: looking-back wrong info

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

> >> > thus making their code likely faster. Users like faster programs.
> >
> > The right way to _encourage_ programmers to use it is to
> > tell them precisely that: "Using LIMIT is recommended - it
> > typically results in faster code."
> >
> > Or "strongly recommended".  Or "You're nuts if you omit LIMIT!"
> > Or whatever other positive or negative encouragement you think
> > might be most effective and appropriate.
> >
> > Telling them nothing about this and, instead, just showing a
> > false signature, does NOT help them.
> 
> This sounds wrong.  The signature change causes warnings on
> all uses that don't specify LIMIT.

No, it does not.  M-: (looking-back "a") returns t or nil.
It does not raise an error.  Likewise, if you evaluate that
sexp in a buffer or *.el file.

The _byte-compiler_ warning has already been mentioned.

> That's how I learnt about the change; I wouldn't have
> updated my code otherwise.

It's not about _updating_ code.  There is nothing new
here.  Not providing LIMIT has always been a bad idea
because of performance.

When you first wrote your code, presumably you consulted
the doc string.  The problem, if you did read the doc,
is that the "general recommendation" there, at the very
end, SAYS NOTHING about LIMIT.  It simply recommends not
to use `looking-back' at all, if you can avoid it.

The right fix is to have the doc do three things:

1. Be honest about the signature.
2. Recommend strongly that you use LIMIT.
3. Say WHY you should use LIMIT: not doing so can lead
   to poor performance.

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.
 
> So changing the advertised signature seems to help, if
> only due to the warning side-effect.

Just fix the doc.  It's not about "upgrading" anything.

NOTHING HAS CHANGED in this function, apart from a minor
doc change and addition of `advertised-calling-convention'.