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

["Drew Adams" <drew.adams@oracle.com>]

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").
 
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.
 
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').
 
But it is more important that nothing is said about what POS is.  At
least it should be said that it is the value of `point' in the current
buffer when the key was pressed, since that seems to always be the case
(?).
 
4. (elisp) `Accessing Mouse' is incomplete.  It does not even mention
key-press events.  Well, of course this is a node about `Accessing
Mouse'.  But in that case the functions that accept key-press events are
documented in the wrong node, since they are not limited to mouse
access/events.
 
It is true that `Accessing Mouse' refers to node `Click Events' for the
form of the return value.  But that description has the same problem wrt
key-press events.
 
When, for Emacs 22, you extended these functions to handle key-press
events, the doc should have been updated properly.  Instead, the Emacs
21 doc was taken as is, with only a "key press" thrown in here and
there.
 
Not clear, consistent, and complete.


In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600)
 of 2013-04-15 on ODIEONE
Bzr revision: 112292
agustin.martin@hispalinux.es-20130415100014-3vaie95fyec9wk37
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -IC:/Devel/emacs/build/include --ldflags -LC:/Devel/emacs/build/lib'