GNU bug report logs - #28736
24.5; doc of `push'

Previous Next

Full log

View this message in rfc822 format

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 28736 <at> debbugs.gnu.org
Subject: bug#28736: 24.5; doc of `push'
Date: Sun, 8 Oct 2017 09:50:37 -0700 (PDT)

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.