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

1 files changed, 11 insertions, 8 deletions

diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index 17a87dd9fd..ce269f087d 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -662,15 +662,18 @@ local on_key_cbs = {} --- @type table<integer,function>
 ---           it won't be invoked for those keys.
 ---@note {fn} will not be cleared by |nvim_buf_clear_namespace()|
 ---
----@param 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.
+---@param 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.
 ---@param ns_id integer? Namespace ID. If nil or 0, generates and returns a
----                     new |nvim_create_namespace()| id.
+---                      new |nvim_create_namespace()| id.
+---
+---@see |keytrans()|
 ---
 ---@return integer Namespace id associated with {fn}. Or count of all callbacks
 ---if on_key() is called without arguments.