bug#24353: 25.1.1: looking-back wrong info

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

> > Anyone getting super serious about the function, and interested
> > beyond the doc string, will look at the code, and will conclude
> > that the signature in the doc string must by a typo (erroneous).
> > And erroneous it is.
> 
> I don't think so. Looking at the code, I see:
>   (declare
>    (advertised-calling-convention (regexp limit &optional greedy) "25.1"))
> How would you conclude that this is a typo?!

Read the initial bug report.  Andreas certainly knew about
the advertised calling convention.  He reported that the
doc shows an incorrect calling convention, which it does.

The doc string communicates an incorrect signature.  (That's
the point of `advertised-calling-convention'.)  If you look
in the code you discover why (as you just did).  From
the code you can see _that_ the doc shows an incorrect
signature (it is not the real signature), and you can see
_why_ it does so (because of `advertised-calling-convention').

It's a judgment call _whether_ we should show the wrong
signature for `looking-back'.  I think no; you think yes.
But the _fact_ that it does not correspond to the real
signature is indisputable.

As Eli pointed out, there are only 28 occurrences of
`advertised-calling-convention' in all of Emacs.  It is
something used very sparingly - precisely because it misleads
(intentionally).  The question is whether the doc of _this_
function should mislead about the signature.

Should this function's doc tell the truth AND offer specific
guidance about the performance implications of LIMIT?  Or
should it lie about the signature and offer NO guidance about
LIMIT?  That's the question raised by this bug report.

(Yes, the byte-compiler offers some guidance now, but it is
limited - just don't-do-it, not why.  But the doc offers none.)