Subject: 24.0.50; doc of `image-display-size'

From: "Drew Adams" <[email-masked]>
Date: Mon, 10 Jan 2011 13:30:38 -0800

The doc string does not say what the function returns.
 
It talks about calculating "the display size" but does not say what is
meant by that.  All the doc really does is describe the implementation:
we say the function calls this or that or the other thing, then this...
 
`image-display-size' is called more than `image-size' is.  The former
appears to be the one of the two that should be better documented,
but there is no explanation of what the "display size" of an image is or
what the difference is between this "wrapper" and what it wraps.
 
And the Elisp manual describes only `image-size', which seems backwards.
 
Finally, saying that the wrapper exists "to handle slice display
properties" explains nothing.  If that is its raison d'etre then
explain that better.  In what way does it "handle" these properties.
I don't mean how it does it but what it does: what is meant by this
handling?  What is the result etc.?

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'