bug#28736: [External] : Re: bug#28736: 24.5; doc of `push'

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

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