Subject: bug#24353: 25.1.1: looking-back wrong info

From: Drew Adams <[email-masked]>
Date: Fri, 2 Sep 2016 13:03:53 -0700 (PDT)

> > This is not a command, for users.  It is a function used by
> > Emacs-Lisp programmers.  Sounds like `C-h f' is becoming less
> > useful, and programmers now need to bypass it and go directly
> > to the source code, just to find out the correct signature.
> 
> The signature is correct, it just advertises LIMIT as a mandatory
> argument.  We could actually make it mandatory, but that would be a
> backward-incompatible change, so a lesser evil has been chosen.
> 
> advertised-calling-convention is used in only 28 places in all of
> Emacs, i.e. it's definitely an extraordinary measure.  So saying that
> "C-h f" becomes less useful cannot even be called an exaggeration.

I know what advertised-calling-convention is.  The argument is
not mandatory.  So the documented signature is NOT correct.
A programmer looking only at the `C-h f' output is misled.
It is perfectly possible to invoke `(looking-back "abc")'.

I see nothing good coming from this change.  Again, if you
are so worried about recommending that programmers not invoke
the function without a LIMIT argument, then say so explicitly
in the doc string.  Do not fake the signature to substitute
for what is a recommendation.

Making the recommendation explicit makes it both clearer
and stronger.  You do not mislead about what the actual
signature is, and you emphasize - call attention to -
the recommended practice of using LIMIT.