docs(lua): clarify when on_key "typed" will be empty (#30774)

1 files changed, 12 insertions, 6 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 4acf8dc0af..aba1ef476b 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1683,12 +1683,15 @@ vim.on_key({fn}, {ns_id})                                       *vim.on_key()*
       • {fn} will not be cleared by |nvim_buf_clear_namespace()|
 
     Parameters: ~
-      • {fn}     (`fun(key: string, typed: string)?`) Function invoked on
-                 every key press. |i_CTRL-V| {key} is the key after mappings
-                 have been applied, and {typed} is the key(s) before mappings
-                 are applied, which may be empty if {key} is produced by
-                 non-typed keys. When {fn} is nil and {ns_id} is specified,
-                 the callback associated with namespace {ns_id} is removed.
+      • {fn}     (`fun(key: string, typed: string)?`) Function invoked for
+                 every input key, after mappings have been applied but before
+                 further processing. Arguments {key} and {typed} are raw
+                 keycodes, where {key} is the key after mappings are applied,
+                 and {typed} is the key(s) before mappings are applied.
+                 {typed} may be empty if {key} is produced by non-typed key(s)
+                 or by the same typed key(s) that produced a previous {key}.
+                 When {fn} is `nil` and {ns_id} is specified, the callback
+                 associated with namespace {ns_id} is removed.
       • {ns_id}  (`integer?`) Namespace ID. If nil or 0, generates and returns
                  a new |nvim_create_namespace()| id.
 
@@ -1696,6 +1699,9 @@ vim.on_key({fn}, {ns_id})                                       *vim.on_key()*
         (`integer`) Namespace id associated with {fn}. Or count of all
         callbacks if on_key() is called without arguments.
 
+    See also: ~
+      • |keytrans()|
+
 vim.paste({lines}, {phase})                                      *vim.paste()*
     Paste handler, invoked by |nvim_paste()|.