bug#14228: 24.3.50; doc of `event-start': nonsensical, incomplete, inconsistent

[Lars Ingebrigtsen]

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

> This pertains to `event-start' and `event-end' (and perhaps to more).
>
> 1. The doc string and (elisp) `Accessing Mouse' do not agree.  The
> former says that arg EVENT can be a "key press event".  The latter
> limits it to mouse events ("the data in a mouse button or motion
> event").

Well, it's in the mouse event section, so it might make sense to just
document the mouse-relevant stuff...

> 2. The doc string of `event-start' specifies the form of EVENT as being
> either (WINDOW POS (0.0) 0) or (WINDOW AREA-OR-POS (X . Y) TIMESTAMP
> OBJECT POS (COL . ROW) IMAGE (DX . DY) (WIDTH . HEIGHT)).
>
> But *none* of those terms are described.  What is POS? IMAGE? OBJECT?
> etc.  Incomprehensible.

Yeah, they might be nice to understand...

> 3. In particular, the doc string says that if EVENT is a key press event
> then the value returned by `event-start' has the form (WINDOW POS (0.0)
> 0).  What is POS?
>
> Anyway, looking at the code and experimenting, it does NOT seem that
> `event-start' always returns the form (WINDOW POS (0.0) 0).  I sometimes
> see a form like this, for instance: (#<window 03FC1840 on foobar> 132
> (231 . 24) 0 nil 132 (33 . 2) nil (0 . 0) (7 . 12)) (which is what is
> returned by `posn-at-point').

Yup.  Eval the following and enter any keystroke:

(event-start (read-event))
=> (#<window 2044 on *unsent wide reply to Drew Adams*> 1660 (0 . 462) 0 nil 
1660 (0 . 21) nil (0 . 0) (11 . 22))

Outdated doc string?

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