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

bug#28736: [External] : Re: 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?
> >
> > 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

Don't look to the Common Lisp Hyperspec as a complete
definition of the language.  It's just a quick way to
get some info (IMO).

Common Lisp The Language (2nd edition) is where to
look.  Especially for design choices, semantics, and
reasons behind the design.

CLTL2 says this about `push' (similarly `pushnew'):

 The effect of (push item place) is roughly equivalent to

 (setf place (cons item place))
 except that the latter would evaluate any subforms of
 place twice, while push takes care to evaluate them
 only once. Moreover, for certain place forms push may
 be significantly more efficient than the setf version.

And what is the effect of `setf' with a cons?  CLTL2
tells us:

 The ultimate result of evaluating a setf form is the
 value of newvalue.

`setf', in all its myriad possibilities, including
user-defined setf methods, is, I think, specified as
returning the new (just set) value.

I agree that the Common Lisp doc could be more explicit
about this, but my reading of it is that `push' returns
the new value - that's part of its specified behavior.

Other readers may disagree.

For `push': 

https://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node149.html

For `setf':

https://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node80.html

Examples (`push', `setf'):

https://www.csee.umbc.edu/courses/331/resources/lisp/LISP-tutorial.html#Setf

___

Note, however, that some things that `setf' _replaced_
in Common Lisp, such as `setcar', do NOT return the
thing updated. `setcar' returns the new car, not the
updated cons.