* bug#7835: 24.0.50; doc string of `overlay-put' needs to mention the return value
@ 2011-01-12 22:45 Drew Adams
2011-07-04 15:32 ` Lars Magne Ingebrigtsen
0 siblings, 1 reply; 7+ messages in thread
From: Drew Adams @ 2011-01-12 22:45 UTC (permalink / raw)
To: 7835
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'
^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#7835: 24.0.50; doc string of `overlay-put' needs to mention the return value
2011-01-12 22:45 bug#7835: 24.0.50; doc string of `overlay-put' needs to mention the return value Drew Adams
@ 2011-07-04 15:32 ` Lars Magne Ingebrigtsen
2011-07-04 18:19 ` Stefan Monnier
0 siblings, 1 reply; 7+ messages in thread
From: Lars Magne Ingebrigtsen @ 2011-07-04 15:32 UTC (permalink / raw)
To: Drew Adams; +Cc: 7835
"Drew Adams" <drew.adams@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/
^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#7835: 24.0.50; doc string of `overlay-put' needs to mention the return value
2011-07-04 15:32 ` Lars Magne Ingebrigtsen
@ 2011-07-04 18:19 ` Stefan Monnier
2011-07-05 13:29 ` Lars Magne Ingebrigtsen
0 siblings, 1 reply; 7+ messages in thread
From: Stefan Monnier @ 2011-07-04 18:19 UTC (permalink / raw)
To: Lars Magne Ingebrigtsen; +Cc: 7835
>> 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
^ permalink raw reply [flat|nested] 7+ messages in thread* bug#7835: 24.0.50; doc string of `overlay-put' needs to mention the return value
2011-07-04 18:19 ` Stefan Monnier
@ 2011-07-05 13:29 ` Lars Magne Ingebrigtsen
2011-07-05 19:00 ` Stefan Monnier
0 siblings, 1 reply; 7+ messages in thread
From: Lars Magne Ingebrigtsen @ 2011-07-05 13:29 UTC (permalink / raw)
To: Stefan Monnier; +Cc: 7835
Stefan Monnier <monnier@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/
^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#7835: 24.0.50; doc string of `overlay-put' needs to mention the return value
2011-07-05 13:29 ` Lars Magne Ingebrigtsen
@ 2011-07-05 19:00 ` Stefan Monnier
2011-07-05 19:08 ` Lars Magne Ingebrigtsen
0 siblings, 1 reply; 7+ messages in thread
From: Stefan Monnier @ 2011-07-05 19:00 UTC (permalink / raw)
To: Lars Magne Ingebrigtsen; +Cc: 7835
>>>> 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
^ permalink raw reply [flat|nested] 7+ messages in thread* bug#7835: 24.0.50; doc string of `overlay-put' needs to mention the return value
2011-07-05 19:00 ` Stefan Monnier
@ 2011-07-05 19:08 ` Lars Magne Ingebrigtsen
2011-07-06 4:03 ` Alp Aker
0 siblings, 1 reply; 7+ messages in thread
From: Lars Magne Ingebrigtsen @ 2011-07-05 19:08 UTC (permalink / raw)
To: Stefan Monnier; +Cc: 7835
Stefan Monnier <monnier@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/
^ permalink raw reply [flat|nested] 7+ messages in thread* bug#7835: 24.0.50; doc string of `overlay-put' needs to mention the return value
2011-07-05 19:08 ` Lars Magne Ingebrigtsen
@ 2011-07-06 4:03 ` Alp Aker
0 siblings, 0 replies; 7+ messages in thread
From: Alp Aker @ 2011-07-06 4:03 UTC (permalink / raw)
To: 7835; +Cc: larsi
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.
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2011-07-06 4:03 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2011-01-12 22:45 bug#7835: 24.0.50; doc string of `overlay-put' needs to mention the return value Drew Adams
2011-07-04 15:32 ` Lars Magne Ingebrigtsen
2011-07-04 18:19 ` Stefan Monnier
2011-07-05 13:29 ` Lars Magne Ingebrigtsen
2011-07-05 19:00 ` Stefan Monnier
2011-07-05 19:08 ` Lars Magne Ingebrigtsen
2011-07-06 4:03 ` Alp Aker
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).