all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* bug#28736: 24.5; doc of `push'
@ 2017-10-08  2:56 Drew Adams
  2017-10-08  6:04 ` Eli Zaretskii
  0 siblings, 1 reply; 9+ messages in thread
From: Drew Adams @ 2017-10-08  2:56 UTC (permalink / raw)
  To: 28736

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'





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#28736: 24.5; doc of `push'
  2017-10-08  2:56 Drew Adams
@ 2017-10-08  6:04 ` Eli Zaretskii
  0 siblings, 0 replies; 9+ messages in thread
From: Eli Zaretskii @ 2017-10-08  6:04 UTC (permalink / raw)
  To: Drew Adams; +Cc: 28736

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#28736: 24.5; doc of `push'
       [not found] ` <<83h8vatbtk.fsf@gnu.org>
@ 2017-10-08 16:50   ` Drew Adams
  2017-10-08 17:15     ` Eli Zaretskii
  0 siblings, 1 reply; 9+ messages in thread
From: Drew Adams @ 2017-10-08 16:50 UTC (permalink / raw)
  To: Eli Zaretskii, Drew Adams; +Cc: 28736

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#28736: 24.5; doc of `push'
  2017-10-08 16:50   ` Drew Adams
@ 2017-10-08 17:15     ` Eli Zaretskii
  0 siblings, 0 replies; 9+ messages in thread
From: Eli Zaretskii @ 2017-10-08 17:15 UTC (permalink / raw)
  To: Drew Adams; +Cc: 28736

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#28736: 24.5; doc of `push'
       [not found]     ` <<83wp45sgrm.fsf@gnu.org>
@ 2017-10-08 17:48       ` Drew Adams
  2017-10-08 18:13         ` Eli Zaretskii
  0 siblings, 1 reply; 9+ messages in thread
From: Drew Adams @ 2017-10-08 17:48 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: 28736

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#28736: 24.5; doc of `push'
  2017-10-08 17:48       ` Drew Adams
@ 2017-10-08 18:13         ` Eli Zaretskii
  2021-09-25 15:41           ` Stefan Kangas
  0 siblings, 1 reply; 9+ messages in thread
From: Eli Zaretskii @ 2017-10-08 18:13 UTC (permalink / raw)
  To: Drew Adams; +Cc: 28736

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#28736: 24.5; doc of `push'
       [not found]         ` <<83tvz9se2s.fsf@gnu.org>
@ 2017-10-08 19:40           ` Drew Adams
  2017-10-09  7:13             ` Andreas Röhler
  0 siblings, 1 reply; 9+ messages in thread
From: Drew Adams @ 2017-10-08 19:40 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: 28736

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#28736: 24.5; doc of `push'
  2017-10-08 19:40           ` bug#28736: 24.5; doc of `push' Drew Adams
@ 2017-10-09  7:13             ` Andreas Röhler
  0 siblings, 0 replies; 9+ messages in thread
From: Andreas Röhler @ 2017-10-09  7:13 UTC (permalink / raw)
  To: 28736

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

^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#28736: 24.5; doc of `push'
  2017-10-08 18:13         ` Eli Zaretskii
@ 2021-09-25 15:41           ` Stefan Kangas
  0 siblings, 0 replies; 9+ messages in thread
From: Stefan Kangas @ 2021-09-25 15:41 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: 28736

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2021-09-25 15:41 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
     [not found] <<<<53afe0a4-8ce5-45fc-9e18-6bf52018c9b6@default>
     [not found] ` <<<<83h8vatbtk.fsf@gnu.org>
     [not found]   ` <<<09655ed0-be2c-4453-9755-224ec733e221@default>
     [not found]     ` <<<83wp45sgrm.fsf@gnu.org>
     [not found]       ` <<9d23e7ad-ff25-4dac-b598-6614b272bebc@default>
     [not found]         ` <<83tvz9se2s.fsf@gnu.org>
2017-10-08 19:40           ` bug#28736: 24.5; doc of `push' Drew Adams
2017-10-09  7:13             ` Andreas Röhler
     [not found] <<<53afe0a4-8ce5-45fc-9e18-6bf52018c9b6@default>
     [not found] ` <<<83h8vatbtk.fsf@gnu.org>
     [not found]   ` <<09655ed0-be2c-4453-9755-224ec733e221@default>
     [not found]     ` <<83wp45sgrm.fsf@gnu.org>
2017-10-08 17:48       ` Drew Adams
2017-10-08 18:13         ` Eli Zaretskii
2021-09-25 15:41           ` Stefan Kangas
     [not found] <<53afe0a4-8ce5-45fc-9e18-6bf52018c9b6@default>
     [not found] ` <<83h8vatbtk.fsf@gnu.org>
2017-10-08 16:50   ` Drew Adams
2017-10-08 17:15     ` Eli Zaretskii
2017-10-08  2:56 Drew Adams
2017-10-08  6:04 ` Eli Zaretskii

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.