bug#28736: 24.5; doc of `push'

bug#28736: 24.5; doc of `push'

[Drew Adams]

Both the doc string and the Elisp manual entry should say that `push'
returns the new value of the place that it updates.  The doc says
nothing about the return value.

The return value is implied by the doc, which says that `push' is
"morally equivalent" to (setf PLACE (cons NEWELT PLACE)), and one
Can figure out that `setf' returns the new value.  But the doc should
just say explicitly what the return value is, instead of making users
dig it out or check the code.

  This is morally equivalent to (setf PLACE (cons NEWELT PLACE)),
  except that PLACE is only evaluated once (after NEWELT).

Also, the use of "morally equivalent" here, though perhaps intended to
be cute, as a joke of sorts, is inappropriate and possibly confusing.
What matters is that the behavior and return value are equivalent, with
the proviso mentioned: that PLACE is evaluated only once (after NEWELT).


In GNU Emacs 24.5.1 (i686-pc-mingw32)
 of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/usr --host=i686-pc-mingw32'

bug#28736: 24.5; doc of `push'

[Eli Zaretskii]

> Date: Sat, 7 Oct 2017 19:56:58 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> Both the doc string and the Elisp manual entry should say that `push'
> returns the new value of the place that it updates.  The doc says
> nothing about the return value.

That usually means we don't want to advertise the return value, and
that programs should not depend on it.  Why is that a problem in this
case?

bug#28736: 24.5; doc of `push'

[Drew Adams]

> > Both the doc string and the Elisp manual entry should say that `push'
> > returns the new value of the place that it updates.  The doc says
> > nothing about the return value.
> 
> That usually means

Usually? Maybe. In this case? Who knows?

> we don't want to advertise the return value, and
> that programs should not depend on it.

Well, now, that would be quite strange in this case. This
is taken directly from Common Lisp (with some functionality
lost), where it is not only prominently documented but it
has also been widely used - for decades.

> Why is that a problem in this case?

No. The right question is why is it a problem to document
this?  This is an important part of the behavior of the
macro. Why should we _not_ inform users about this useful
feature?

This is no different (zero difference, in fact) from
documenting that `setq' returns the value of its (last)
assignment.

(Not to mention that we document the return value of `pop'.)

bug#28736: 24.5; doc of `push'

[Eli Zaretskii]

> Date: Sun, 8 Oct 2017 09:50:37 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 28736@debbugs.gnu.org
> 
> > Why is that a problem in this case?
> 
> No. The right question is why is it a problem to document
> this?

<Shrug> Because we don't want to guarantee the return value won't
change in the future?

bug#28736: 24.5; doc of `push'

[Drew Adams]

> > The right question is why is it a problem to document this?
> 
> <Shrug> Because we don't want to guarantee the return value won't
> change in the future?

Are you sure?  When was that decided?  Just now?

Why would we want to do that?  Gratuitously acting different
from Common Lisp (and all other Lisps?) in this case wouldn't
seem to be advantageous.  Do you see a good reason to do that?

And why "<Shrug>"?  I wonder if your answer might have been
different if a different person had filed this bug...

bug#28736: 24.5; doc of `push'

[Eli Zaretskii]

> Date: Sun, 8 Oct 2017 10:48:32 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 28736@debbugs.gnu.org
> 
> > > The right question is why is it a problem to document this?
> > 
> > <Shrug> Because we don't want to guarantee the return value won't
> > change in the future?
> 
> Are you sure?

No.

> When was that decided?

I don't know if it was decided and when, I was just wondering whether
the lack of documentation is deliberate or an omission.

> Just now?

That's uncalled-for.

> And why "<Shrug>"?  I wonder if your answer might have been
> different if a different person had filed this bug...

Why would you wonder about that?  Have I ever treated your bug reports
different from anyone else's?

bug#28736: 24.5; doc of `push'

[Drew Adams]

> > > > why is it a problem to document this?
> > >
> > > <Shrug> Because we don't want to guarantee the return
> > > value won't change in the future?
> >
> > Are you sure?
> 
> No.
> 
> > When was that decided?
> 
> I don't know if it was decided and when, I was just wondering
> whether the lack of documentation is deliberate or an omission.

Good.  Neither do I know that we don't want to guarantee
that the return value won't change.  Nor do I know whether
the lack of documentation was deliberate or not.  Nor do I
know a reason why we wouldn't want to document the behavior,
guarantee or no guarantee. 

Not having any reason to think there was a deliberate
decision not to document this, and not knowing any good
reason why it should not be documented, whether it was
deliberate or (a priori more likely) an oversight, and
knowing good reasons why it _should_ be documented (it
is useful, and documenting that use is the practice in
Lisp in general, and it fits what we do for things like
`setq'), this should be a no-brainer, IMO.

But if there is a good reason why it should not be
documented, let's hear it, please.

bug#28736: 24.5; doc of `push'

[Andreas Röhler]

[-- Attachment #1: Type: text/plain, Size: 1192 bytes --]



On 08.10.2017 21:40, Drew Adams wrote:
>>>>> why is it a problem to document this?
>>>> <Shrug> Because we don't want to guarantee the return
>>>> value won't change in the future?
>>> Are you sure?
>> No.
>>
>>> When was that decided?
>> I don't know if it was decided and when, I was just wondering
>> whether the lack of documentation is deliberate or an omission.
> Good.  Neither do I know that we don't want to guarantee
> that the return value won't change.  Nor do I know whether
> the lack of documentation was deliberate or not.  Nor do I
> know a reason why we wouldn't want to document the behavior,
> guarantee or no guarantee.
>
> Not having any reason to think there was a deliberate
> decision not to document this, and not knowing any good
> reason why it should not be documented, whether it was
> deliberate or (a priori more likely) an oversight, and
> knowing good reasons why it _should_ be documented (it
> is useful, and documenting that use is the practice in
> Lisp in general, and it fits what we do for things like
> `setq'), this should be a no-brainer, IMO.
>
> But if there is a good reason why it should not be
> documented, let's hear it, please.
>
>
>

+1

[-- Attachment #2: Type: text/html, Size: 1984 bytes --]

bug#28736: 24.5; doc of `push'

[Stefan Kangas]

tags 28736 wontfix notabug
close 28736
thanks

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Sun, 8 Oct 2017 10:48:32 -0700 (PDT)
>> From: Drew Adams <drew.adams@oracle.com>
>> Cc: 28736@debbugs.gnu.org
>>
>> > > The right question is why is it a problem to document this?
>> >
>> > <Shrug> Because we don't want to guarantee the return value won't
>> > change in the future?
>>
>> Are you sure?
>
> No.

The question here is if the return value of `push' should be documented.

I took a look at Common Lisp, and they do not document its return
value.[1]  I think it's fine for us to also not document it, unless someone
can show a clear reason why it should be.

I'm therefore closing this bug report.

Footnotes:
[1]  http://clhs.lisp.se/Body/m_push.htm