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

[Drew Adams]

The doc string does not tell you what you need to know.
 
Look at the code for `image-dired-dired-toggle-marked-thumbs', for
instance.  You will see that it makes use of the `put-image' overlay
property (to gather the right overlay(s)).  That property was added by
the call to function `put-image'.
 
But there is nothing in the doc for function `put-image' that mentions
that it adds property `put-image' to the overlay that it creates.
 
In fact, the doc says nothing about this overlay, just calling it "an
overlay".  Well, at least it says that the overlay has a `before-string'
string with a `display' property whose value is the image.
 
1. The doc should mention the `put-image' property, which is the only
way for you to recognize such an overlay AFAICT.
 
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.

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'