feat(lua): allow vim.on_key() callback to consume the key (#30939)

1 files changed, 11 insertions, 9 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 74a0ba821a..6ae1a1a3b8 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1635,7 +1635,7 @@ vim.notify_once({msg}, {level}, {opts})                    *vim.notify_once()*
     Return: ~
         (`boolean`) true if message was displayed, else false
 
-vim.on_key({fn}, {ns_id})                                       *vim.on_key()*
+vim.on_key({fn}, {ns_id}, {opts})                               *vim.on_key()*
     Adds Lua function {fn} with namespace id {ns_id} as a listener to every,
     yes every, input key.
 
@@ -1649,17 +1649,19 @@ 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 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
+      • {fn}     (`fun(key: string, typed: string): 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}. If {fn} returns an empty string, {key} is
+                 discarded/ignored. When {fn} is `nil`, 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.
+      • {opts}   (`table?`) Optional parameters
 
     Return: ~
         (`integer`) Namespace id associated with {fn}. Or count of all