bug#26626: 24.5; doc of `last-command-event' and `last-nonmenu-event'

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

> > The essential difference in the descriptions seems to be the last input
> > event read "as part of a key sequence" versus read "as part of a
> > command".  But "read as part of a command" is unclear.  Does it mean
> > read by a command (e.g., by a call to `read-char' within the command
> > definition)?  No.  But that's all I can think of, when reading that
> > description.
> >
> > The doc of `last-nonmenu-event' is pretty clear.  Or at least it is
> > before reading also the doc of `last-command-event' and trying to make
> > sense of that.  Even the name of the latter is unclear - what's a
> > "command event"?
> >
> > The example given for `last-command-event' suggests that what is
> > meant is the last event in the key sequence that invoked/initiated a
> > command.  I think that's closer to what the meaning/behavior is.
> 
> The variable doc string isn't very helpful; no.
> 
> I've now changed it to the following on the trunk:
> 
> Last input event that was part of a command key sequence.
> See Info node `(elisp)Command Loop Info'.

There's no such thing as a "command key sequence",
as opposed, one imagines, to a "non-command key
sequence".  A key sequence that is complete is
always bound to a command.

Or did you mean to suggest a complete key sequence,
as opposed to an incomplete sequence: a key-sequence
prefix?

There are events that are not key sequences.  That
distinction is valid and important.  But are there
(complete) key sequences that are not bound to keys
(including menu and mouse actions)?  I don't think
so.

I still think that the text for this should borrow
from what is said for `last-nonmenu-event'.  IIUC,
`last-command-event' is the "last input event read
as part of a key sequence".

IOW, same as `last-nonmenu-event', but without the
"nonmenu" part.  Isn't that the essential difference?

And yes, the Info description should be changed,
not just the doc string, for the reasons given in
the bug description - "as part of a command" is
misleading or meaningless.  See above for a
suggestion: make it similar to what we say for
`last-nonmenu-event'.