bug#24353: 25.1.1: looking-back wrong info

bug#24353: 25.1.1: looking-back wrong info

[Andreas Röhler]

Wrong advertised-calling-convention

 From subr.el: looking-back declares optional argument LIMIT mandatory.

Such calling-convention deserves a place in doku, but should not send 
wrong info out of didactics

GNU Emacs 25.1.1 (i686-pc-linux-gnu, GTK+ Version 3.14.5) of 2016-08-22

bug#24353: 25.1.1: looking-back wrong info

[Eli Zaretskii]

> From: Andreas Röhler <andreas.roehler@easy-emacs.de>
> Date: Fri, 2 Sep 2016 10:48:39 +0200
> 
> Wrong advertised-calling-convention
> 
>  From subr.el: looking-back declares optional argument LIMIT mandatory.
> 
> Such calling-convention deserves a place in doku, but should not send 
> wrong info out of didactics

Are you saying that using advertised-calling-convention is wrong
everywhere, or just in this one case?  If the latter, what is special
about this function?

Thanks.

bug#24353: 25.1.1: looking-back wrong info

[Andreas Röhler]

On 02.09.2016 10:58, Eli Zaretskii wrote:
>> From: Andreas Röhler <andreas.roehler@easy-emacs.de>
>> Date: Fri, 2 Sep 2016 10:48:39 +0200
>>
>> Wrong advertised-calling-convention
>>
>>   From subr.el: looking-back declares optional argument LIMIT mandatory.
>>
>> Such calling-convention deserves a place in doku, but should not send
>> wrong info out of didactics
> Are you saying that using advertised-calling-convention is wrong
> everywhere,

In the way it's implemented, seems a bad idea everywhere.
It cheats the user delivering wrong resp. incomplete signatures.

If certain usages are discouraged, that might be told in docstring, by 
re-writing the function etc.

>   or just in this one case?  If the latter, what is special
> about this function?
>
> Thanks.

bug#24353: 25.1.1: looking-back wrong info

[Eli Zaretskii]

> Cc: 24353@debbugs.gnu.org
> From: Andreas Röhler <andreas.roehler@easy-emacs.de>
> Date: Fri, 2 Sep 2016 11:57:53 +0200
> 
> > Are you saying that using advertised-calling-convention is wrong
> > everywhere,
> 
> In the way it's implemented, seems a bad idea everywhere.
> It cheats the user delivering wrong resp. incomplete signatures.
> 
> If certain usages are discouraged, that might be told in docstring, by 
> re-writing the function etc.

But advertised-calling-convention affects the doc string, and nothing
else.  Both the source and the Lisp interpreter ignore it.  So it
seems its effect is exactly what you are asking for: to tell in the
doc string that we would like it to be used this way.

bug#24353: 25.1.1: looking-back wrong info

[Drew Adams]

FWIW, I agree with Andreas.  Or at least I have a question as
to why this was changed (from longstanding practice for this
function's doc).

The *only* difference I see in the output of `C-h f
looking-back', between Emacs 24.5 and my most recent pre-Emacs
25 snapshot (which is not very recent, admittedly) is the false
signature (looking-back REGEXP LIMIT &optional GREEDY) instead
of the correct signature (looking-back REGEXP &optional LIMIT
GREEDY).

How does this change help Emacs users?

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.

If it is so important that people provide LIMIT then spell
that out _explicitly_ in the doc as a recommendation.  It
should be a no-no to just change the advertized signature of
a function, without changing the actual signature (code) and
without otherwise changing the doc.

bug#24353: 25.1.1: looking-back wrong info

[Eli Zaretskii]

> Date: Fri, 2 Sep 2016 10:51:01 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 24353@debbugs.gnu.org
> 
> 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.

bug#24353: 25.1.1: looking-back wrong info

[Dmitry Gutov]

On 02.09.2016 20:51, Drew Adams wrote:

> How does this change help Emacs users?

It forces Emacs Lisp programmers to include the last argument, thus 
making their code likely faster. Users like faster programs.

> If it is so important that people provide LIMIT then spell
> that out _explicitly_ in the doc as a recommendation.

That's very easy to miss. And like Eli said, the choice was between this 
and _actually_ changing the signature. I imagine you would like the 
latter choice even less.

> It
> should be a no-no to just change the advertized signature of
> a function, without changing the actual signature (code) and
> without otherwise changing the doc.

You have some point there, but mentioning the last argument in the 
docstring would be rather awkward, considering it's absent in the 
advertised signature.

bug#24353: 25.1.1: looking-back wrong info

[Drew Adams]

> > How does this change help Emacs users?
> 
> It forces Emacs Lisp programmers to include the last argument,

It certainly does not.  It does NOT force anything.
It only misleads.  It doesn't even explicitly recommend.

> 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.

> > If it is so important that people provide LIMIT then spell
> > that out _explicitly_ in the doc as a recommendation.
> 
> That's very easy to miss.

It's nowhere near as easy to miss as just moving LIMIT before
&optional in the printed (and false) signature.

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.

An explicit recommendation is quite effective.  It can be as
strong and as noticeable as you like, or as gentle and quiet
as you like.

> And like Eli said, the choice was between this and
> _actually_ changing the signature.

No, that was not the only choice.  The desired change is
(apparently) to pass a strong recommendation message, in
order to affect programmer behavior.  That doesn't happen
just by faking a signature.

If you want to change behavior, let programmers know that -
explicitly.  Telling them the (positive) effect of LIMIT is
the best way to get them to use it.

> I imagine you would like the latter choice even less.

It doesn't really affect me, personally.  But yes, that
would be quite unwise, for Emacs users and code generally.

If it aint broke, don't fix it.  Is it _sufficiently
important_ that code uses LIMIT that you need to break
backward compatibility?  If so, then you have no choice
but to break it.  But that is the question.

> > It should be a no-no to just change the advertized
> > signature of a function, without changing the actual
> > signature (code) and without otherwise changing the doc.
> 
> You have some point there, but mentioning the last argument in the
> docstring would be rather awkward, considering it's absent in the
> advertised signature.

Sorry, but I have no idea what you mean by that.

This doc-string change seems doubly bad, in fact:

1. The signature that is shown is false.

2. We removed this sentence, which was the only suggestion
   related to performance:

   "As a general recommendation, try to avoid using
    `looking-back' wherever possible, since it is slow."

If that vague recommendation is not accurate or is not
strong enough, then replace it with a more accurate or
stronger one.

But don't just say NOTHING about performance and NOTHING
about the effect of LIMIT on performance, if that's what
this is really all about.

Programmers and other users are not dumb "losers".  They
are smart enough to understand what you have to say to
them about LIMIT.  Just say it - explicitly.

bug#24353: 25.1.1: looking-back wrong info

[Dmitry Gutov]

On 03.09.2016 02:59, Drew Adams wrote:
>>> How does this change help Emacs users?
>>
>> It forces Emacs Lisp programmers to include the last argument,
>
> It certainly does not.  It does NOT force anything.
> It only misleads.  It doesn't even explicitly recommend.

Well, at least the byte compiler sees the advertised calling convention, 
and warns when it's violated. So the encouragement is there.

bug#24353: 25.1.1: looking-back wrong info

[Drew Adams]

> >>> How does this change help Emacs users?
> >>
> >> It forces Emacs Lisp programmers to include the last argument,
> >
> > It certainly does not.  It does NOT force anything.
> > It only misleads.  It doesn't even explicitly recommend.
> 
> Well, at least the byte compiler sees the advertised calling convention,
> and warns when it's violated. So the encouragement is there.

That's true, and a good point.

It's misleading to show the signature wrong.  It's
especially unhelpful to do ONLY that.

Encouragement, recommendation, admonition, and even warning,
can help.  The more explicit, the better.  The more it helps
users _understand_ (e.g., say WHY), the better.

bug#24353: 25.1.1: looking-back wrong info

[npostavs]

Drew Adams <drew.adams@oracle.com> writes:
>
> 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.

So something like this:

diff --git i/lisp/subr.el w/lisp/subr.el
index e9e19d3..4d1267a 100644
--- i/lisp/subr.el
+++ w/lisp/subr.el
@@ -3533,7 +3533,10 @@ looking-back
 LIMIT.
 
 As a general recommendation, try to avoid using `looking-back'
-wherever possible, since it is slow."
+wherever possible, since it is slow.
+
+For backwards compatibility LIMIT may be omitted, but this usage
+is deprecated."
   (declare
    (advertised-calling-convention (regexp limit &optional greedy) "25.1"))
   (let ((start (point))

>> > It should be a no-no to just change the advertized
>> > signature of a function, without changing the actual
>> > signature (code) and without otherwise changing the doc.
>> 
>> You have some point there, but mentioning the last argument in the
>> docstring would be rather awkward, considering it's absent in the
>> advertised signature.

The number (and names) of arguments have not been changed.

>
> 2. We removed this sentence, which was the only suggestion
>    related to performance:
>
>    "As a general recommendation, try to avoid using
>     `looking-back' wherever possible, since it is slow."

Not sure which version you're looking at, but that sentence is still
present on both emacs-25 and master branches.

bug#24353: 25.1.1: looking-back wrong info

[Dmitry Gutov]

On 03.09.2016 03:14, npostavs@users.sourceforge.net wrote:

>>> You have some point there, but mentioning the last argument in the
>>> docstring would be rather awkward, considering it's absent in the
>>> advertised signature.
>
> The number (and names) of arguments have not been changed.

Indeed, that was nonsense. Sorry.

bug#24353: 25.1.1: looking-back wrong info

[Drew Adams]

> > 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.
> 
> So something like this:
> 
> diff --git i/lisp/subr.el w/lisp/subr.el
> index e9e19d3..4d1267a 100644
> --- i/lisp/subr.el
> +++ w/lisp/subr.el
> @@ -3533,7 +3533,10 @@ looking-back
>  LIMIT.
> 
>  As a general recommendation, try to avoid using `looking-back'
> -wherever possible, since it is slow."
> +wherever possible, since it is slow.
> +
> +For backwards compatibility LIMIT may be omitted, but this usage
> +is deprecated."
>    (declare
>     (advertised-calling-convention (regexp limit &optional greedy)
> "25.1"))
>    (let ((start (point))

Dunno.  Is it deprecated?  If so, that presumably means that
at some point it is likely to be desupported (impossible to
omit LIMIT).

Anyway, I've said everything I think I think about this doc.
What you do now, if anything, depends on the effect sought.

> > 2. We removed this sentence, which was the only suggestion
> >    related to performance:
> >    "As a general recommendation, try to avoid using
> >     `looking-back' wherever possible, since it is slow."
> 
> Not sure which version you're looking at, but that sentence is still
> present on both emacs-25 and master branches.

Sorry, my bad.  It is present.  It was hiding below a 1/2-frame
window view, and I thought the whole buffer was shown.  Darn
MS Windows scroll bars - they're there whether there is content
to scroll or not.

bug#24353: 25.1.1: looking-back wrong info

[Clément Pit--Claudel]

[-- Attachment #1.1: Type: text/plain, Size: 851 bytes --]

On 2016-09-02 19:59, Drew Adams wrote:
>> > 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.  That's how I learnt about the change; I wouldn't have updated my code otherwise.

So changing the advertised signature seems to help, if only due to the warning side-effect.

Clément.


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

bug#24353: 25.1.1: looking-back wrong info

[Drew Adams]

> >> > 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'.

bug#24353: 25.1.1: looking-back wrong info

[Clément Pit--Claudel]

[-- Attachment #1.1: Type: text/plain, Size: 1101 bytes --]

On 2016-09-03 14:10, Drew Adams wrote:

> 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.

Maybe? Or maybe I knew looking-at and used eldoc to get the signature. I can't recall.

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

Right.  And the addition of the advertised-calling-convention caused me, and perhaps others, to revisit existing code that did not include a limit.

So it was a neat addition, since the misleading doc string, or my own carelessness, caused me to make mistakes in the past. Fortunately, these mistakes are now fixed, because I got byte-compilation warnings.  Very convenient.

Of course, upgrading the docstring could still be a good idea; but I don't make the mistake anymore, since when I write new calls to this function eldoc asks me to add the LIMIT argument, so mostly don't care about that update.

Clément.


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

bug#24353: 25.1.1: looking-back wrong info

[npostavs]

Drew Adams <drew.adams@oracle.com> writes:

> 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.

> 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.

>
> 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.

bug#24353: 25.1.1: looking-back wrong info

[Drew Adams]

> > 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?

bug#24353: 25.1.1: looking-back wrong info

[Michael Heerdegen]

Drew Adams <drew.adams@oracle.com> writes:

> And yes, "the whole point of advertised-calling-convention is to
> advertise a signature different from the actual implemented one."

I always thought this would be just a temporary, intermediate state,
and the second argument will be made mandatory soon (is that wrong?).

With other words, we already give the impression that the second arg is
mandatory, in all regards, to force people to change their code.  But we
don't break old code yet, it is still running, until some later version.

And I think this is good: you can still supply (point-min) as limit if
you really don't care, but you should make the decision, because it is
important to make that decision consciously, and that's why we make the
LIMIT arg mandatory.

Sure, the effect of `advertized-calling-convention' could be improved to
be less confusing, e.g. it could add automatically to the doc something
like "the old signature ... is obsolete but currently still supported"
or so.

If we use `advertized-calling-convention' for anything else then
obsoleting signatures - like giving recommendations of how to call a
function the best way, I would agree that this would not be a good
thing, and it would be better to use the documentation string for this
purpose.


Michael.

bug#24353: 25.1.1: looking-back wrong info

[Clément Pit--Claudel]

[-- Attachment #1.1: Type: text/plain, Size: 455 bytes --]

On 2016-09-02 19:59, Drew Adams wrote:
> 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?!


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

bug#24353: 25.1.1: looking-back wrong info

[Drew Adams]

> > 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.)

bug#24353: 25.1.1: looking-back wrong info

[Eli Zaretskii]

> Date: Sat, 3 Sep 2016 11:42:11 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> 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.

That decision was already made.

bug#24353: 25.1.1: looking-back wrong info

[Drew Adams]

> > 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.