bug#6130: 23.1; artist-mode spray-can malfunction

[Daniel Koning <dk@danielkoning.com>]

Eli Zaretskii <eliz@gnu.org> writes:

> We do that all the time.  For example:
>
>   (display-graphic-p &optional DISPLAY)
>
>   Return non-nil if DISPLAY is a graphic display.
>   [...]
>   DISPLAY can be a display name, a frame, or nil (meaning the selected
>   frame's display).

From a user perspective, there is a crucial distinction between these
two examples of ambiguous naming.

When an argument is called DISPLAY even though it can be other things
besides a display, the function still works in every case that its name
and its arguments' names suggest that it should work.

But when the return value is called WINDOW when it might not be one,
then it becomes a source of potential error merely to rely on the
function to behave as its name suggests. Sure, you can write
documentation to warn users about the pitfall, but misleading naming
conventions are one of the factors that cause people to write mistaken
documentation. (Cf. the documentation of `posn-window' until a few days
ago!)

> In polymorphic interfaces, the alternative is to say
> DISPLAY-OR-FRAME-OR-... which is too tedious.

If that's the main problem with assigning accurate names in polymorphic
contexts -- that the names end up too long when you include every
possible type -- how about defining a supertype which includes (in this
case) both windows and frames?  That may seem cumbersome, but realize
that this is effectively what is already happening, insofar as "window"
is being coerced into serving as metonymy for the entire class of
mouse-position containers.

Daniel