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

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

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

On its own, that is a reasonable argument.  The problem with that is
that these functions are, for some reason, documented ONLY in this
node, i.e., in the context of mouse events.  But they are general 
functions, not limited to mouse events.

Ideally their doc should be moved elsewhere (and a cross-ref added
to this node, to point there).  But whether it is thus moved or not,
the functions need to be documented properly.  Their generality does
not change, nor should their descriptions change, just because they
are documented in a mouse-specific node.

IOW, the first fix is to make the descriptions general.  If we can
then also move those corrected descriptions elsewhere, so much the
better.

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

Incomplete anyway, and perhaps incorrect.