bug#7834: 24.0.50; doc of `put-image'

[Stefan Monnier]

>> 2. Why not have `put-image' return the overlay itself?  That would
>> simplify code such as that of `image-dired-dired-toggle-marked-thumbs',
>> which, just after calling `put-image', tries to examine all overlays at
>> point just to find the right one - the one with a `put-image' property.

> That's a good idea.  Stefan, however, is really against primarily
> side-effect-ey functions returning usable values, so we should check
> with him first.

This function creates a new object, and that's a good idea to return it.
The cases to which I'm opposed is when the function returns something
which the caller knows even before calling the function.


        Stefan