bug#28736: 24.5; doc of `push'

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

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'