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

From: Lars Ingebrigtsen <[email-masked]>
Date: Fri, 26 Jul 2019 11:33:07 +0200

Drew Adams <[email-masked]> 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