GNU bug report logs - #7835
24.0.50; doc string of `overlay-put' needs to mention the return value

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 7835 in the body.
You can then email your comments to 7835 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.0.50; doc string of `overlay-put' needs to mention the return value
Date: Wed, 12 Jan 2011 14:45:50 -0800

Like the Elisp manual, the doc string of `overlay-put' needs to mention
that it returns its 3rd arg.
 

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-01-03 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4) --no-opt --cflags
-Ic:/imagesupport/include'
 

Message #12 received at 7835 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 7835 <at> debbugs.gnu.org
Subject: Re: 24.0.50;
	doc string of `overlay-put' needs to mention the return value
Date: Mon, 04 Jul 2011 17:32:54 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:

> Like the Elisp manual, the doc string of `overlay-put' needs to mention
> that it returns its 3rd arg.

Ok; fixed.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #15 received at 7835 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
Cc: Drew Adams <drew.adams <at> oracle.com>, 7835 <at> debbugs.gnu.org
Subject: Re: bug#7835: 24.0.50;
	doc string of `overlay-put' needs to mention the return value
Date: Mon, 04 Jul 2011 14:19:45 -0400

>> Like the Elisp manual, the doc string of `overlay-put' needs to mention
>> that it returns its 3rd arg.

Actually, the right fix would be to not document it.


        Stefan

Message #18 received at 7835 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: Drew Adams <drew.adams <at> oracle.com>, 7835 <at> debbugs.gnu.org
Subject: Re: bug#7835: 24.0.50;
	doc string of `overlay-put' needs to mention the return value
Date: Tue, 05 Jul 2011 15:29:49 +0200

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

>>> Like the Elisp manual, the doc string of `overlay-put' needs to mention
>>> that it returns its 3rd arg.
>
> Actually, the right fix would be to not document it.

Knowing that you're able to say

  (push (overlay-put ... ... (get-some-value)) list)

sounds useful to me.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #21 received at 7835 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
Cc: Drew Adams <drew.adams <at> oracle.com>, 7835 <at> debbugs.gnu.org
Subject: Re: bug#7835: 24.0.50;
	doc string of `overlay-put' needs to mention the return value
Date: Tue, 05 Jul 2011 15:00:31 -0400

>>>> Like the Elisp manual, the doc string of `overlay-put' needs to mention
>>>> that it returns its 3rd arg.
>> Actually, the right fix would be to not document it.
> Knowing that you're able to say
>   (push (overlay-put ... ... (get-some-value)) list)
> sounds useful to me.

Looks like bad style to me.


        Stefan

Message #24 received at 7835 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: Drew Adams <drew.adams <at> oracle.com>, 7835 <at> debbugs.gnu.org
Subject: Re: bug#7835: 24.0.50;
	doc string of `overlay-put' needs to mention the return value
Date: Tue, 05 Jul 2011 21:08:16 +0200

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

>>>>> Like the Elisp manual, the doc string of `overlay-put' needs to mention
>>>>> that it returns its 3rd arg.
>>> Actually, the right fix would be to not document it.
>> Knowing that you're able to say
>>   (push (overlay-put ... ... (get-some-value)) list)
>> sounds useful to me.
>
> Looks like bad style to me.

I don't think so.  It's how setf and most mutators in Common Lisp
work, for instance:

MAINT> (setq table (make-hash-table))
#<EQL Hash Table{0} 402000AD6B>
MAINT> (setf (gethash :bar table) :foo)
:FOO

Or elisp put:

(put 'put 'foo 'bar)
=> bar

Now, you may consider `overlay-put' more like `insert', and not like a
`setf'-like mutator, but to me I'd be surprised if it didn't act like
these other mutators.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #27 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Alp Aker <alp.tekin.aker <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Cc: larsi <at> gnus.org, monnier <at> iro.umontreal.ca
Subject: Re: bug#7835: 24.0.50;
	doc string of `overlay-put' needs to mention the return value
Date: Wed, 06 Jul 2011 00:03:45 -0400

Lars Magne Ingebrigtsen writes:

>> Looks like bad style to me.
>
> I don't think so.  It's how setf and most mutators in Common Lisp
> work, for instance:
>
> MAINT> (setq table (make-hash-table))
> #<EQL Hash Table{0} 402000AD6B>
> MAINT> (setf (gethash :bar table) :foo)
> :FOO

The point was not that there's something wrong with the value
`overlay-put' returns.  Rather, the rasion d'être of `overlay-put' is
its side effect, and it's bad style to make use of the return value of a
function that's called for its side effect(s).  If you accept this view,
then it's reasonable to say that the return value of such functions
needn't be documented, as that encourages people to make use their
return values.

OTOH, the ubiquity of contructions like:

  (set (make-local-variable 'foo) 'bar)

might be taken as justification for the claim that, in the case of
certain functions unique to Elisp, using return values in this way is
idiomatic Elisp, and that `overlay-put' is such a function.  But that
argument strikes me as a weak.

Previous Next

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