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

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'
 

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

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> 1. The doc should mention the `put-image' property, which is the only
> way for you to recognize such an overlay AFAICT.

I've now done this.

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

Stefan?

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

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

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

[Lars Magne Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

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

Okidoke.

I'll mark this bug as "pending", since changing the return value of
`put-image' is a new feature (and may possibly break something that
relied on the un-announced old value).

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

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

[Stefan Monnier]

> I'll mark this bug as "pending", since changing the return value of
> `put-image' is a new feature (and may possibly break something that
> relied on the un-announced old value).

OK.  You can also install the change in the `pending' branch and close
the bug as "fixed in 24.2".


        Stefan

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

[Lars Magne Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> I'll mark this bug as "pending", since changing the return value of
>> `put-image' is a new feature (and may possibly break something that
>> relied on the un-announced old value).
>
> OK.  You can also install the change in the `pending' branch and close
> the bug as "fixed in 24.2".

For me it easier to just mark it as pending.  Having a long-lived tree
that will need to be merged back later can be a bit complicated, in my
experience. 

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

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

[Lars Magne Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

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

I've now installed this change.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/