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.