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

From: Eli Zaretskii <[email-masked]>
Date: Sat, 24 Jan 2015 10:12:51 +0200

> From: Daniel Koning <[email-masked]>
> Cc: Stefan Monnier <[email-masked]>,  [email-masked],  [email-masked],  [email-masked]
> Date: Fri, 23 Jan 2015 15:52:54 -0600
> 
> 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!)

I agree that the documentation was (or maybe still is) in the need of
improvement (documentation of events is quite obscure, to tell the
truth, and was like that for a very long time).  But I fail to see the
crucial difference between these two examples.  In any case, the
example I brought up was just the first thing that popped up in my
mind, you can find plenty of examples of the other kind as well.

IOW, in Emacs one must read the documentation before they believe the
literal meaning of an argument's name.

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

Try proposing one, maybe we will adopt it.  However, we have bad
experience with terminology that only Emacs uses, or, worse, where the
Emacs meaning is different from that of the rest of the world.  So I'm
not sure this path is better.