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

[Lars Ingebrigtsen]

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

> The doc is not very clear - both (elisp) `Command Loop Info' and the doc
> strings.

I think the manual is pretty clear:

---

@defvar last-command-event
This variable is set to the last input event that was read by the
command loop as part of a command.  The principal use of this variable
is in @code{self-insert-command}, which uses it to decide which
character to insert.

@example
@group
last-command-event
;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
     @result{} 5
@end group
@end example

@noindent
The value is 5 because that is the @acronym{ASCII} code for @kbd{C-e}.
@end defvar

---

The example helps a lot.  

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

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