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

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

[Drew Adams]

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'
 

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

[Lars Magne Ingebrigtsen]

"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/

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

[Stefan Monnier]

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

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

[Lars Magne Ingebrigtsen]

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/

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

[Stefan Monnier]

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

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

[Lars Magne Ingebrigtsen]

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/

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

[Alp Aker]

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.