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