refactor(lua): vim.keymap.set tests, docs #30511

3 files changed, 56 insertions, 29 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 5a70852649..ef6f2de95f 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2847,24 +2847,24 @@ vim.keymap.del({modes}, {lhs}, {opts})                      *vim.keymap.del()*
       • |vim.keymap.set()|
 
 vim.keymap.set({mode}, {lhs}, {rhs}, {opts})                *vim.keymap.set()*
-    Adds a new |mapping|. Examples: >lua
-        -- Map to a Lua function:
-        vim.keymap.set('n', 'lhs', function() print("real lua function") end)
-        -- Map to multiple modes:
-        vim.keymap.set({'n', 'v'}, '<leader>lr', vim.lsp.buf.references, { buffer = true })
-        -- Buffer-local mapping:
-        vim.keymap.set('n', '<leader>w', "<cmd>w<cr>", { silent = true, buffer = 5 })
-        -- Expr mapping:
+    Defines a |mapping| of |keycodes| to a function or keycodes.
+
+    Examples: >lua
+        -- Map "x" to a Lua function:
+        vim.keymap.set('n', 'x', function() print("real lua function") end)
+        -- Map "<leader>x" to multiple modes for the current buffer:
+        vim.keymap.set({'n', 'v'}, '<leader>x', vim.lsp.buf.references, { buffer = true })
+        -- Map <Tab> to an expression (|:map-<expr>|):
         vim.keymap.set('i', '<Tab>', function()
           return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>"
         end, { expr = true })
-        -- <Plug> mapping:
+        -- Map "[%%" to a <Plug> mapping:
         vim.keymap.set('n', '[%%', '<Plug>(MatchitNormalMultiBackward)')
 <
 
     Parameters: ~
-      • {mode}  (`string|string[]`) Mode short-name, see |nvim_set_keymap()|.
-                Can also be list of modes to create mapping on multiple modes.
+      • {mode}  (`string|string[]`) Mode "short-name" (see
+                |nvim_set_keymap()|), or a list thereof.
       • {lhs}   (`string`) Left-hand side |{lhs}| of the mapping.
       • {rhs}   (`string|function`) Right-hand side |{rhs}| of the mapping,
                 can be a Lua function.
diff --git a/runtime/lua/vim/keymap.lua b/runtime/lua/vim/keymap.lua
index ec00c56c7a..50ca0d2d0e 100644
--- a/runtime/lua/vim/keymap.lua
+++ b/runtime/lua/vim/keymap.lua
@@ -15,30 +15,28 @@ local keymap = {}
 --- (Default: `false`)
 --- @field remap? boolean
 
---- Adds a new |mapping|.
+--- Defines a |mapping| of |keycodes| to a function or keycodes.
+---
 --- Examples:
 ---
 --- ```lua
---- -- Map to a Lua function:
---- vim.keymap.set('n', 'lhs', function() print("real lua function") end)
---- -- Map to multiple modes:
---- vim.keymap.set({'n', 'v'}, '<leader>lr', vim.lsp.buf.references, { buffer = true })
---- -- Buffer-local mapping:
---- vim.keymap.set('n', '<leader>w', "<cmd>w<cr>", { silent = true, buffer = 5 })
---- -- Expr mapping:
+--- -- Map "x" to a Lua function:
+--- vim.keymap.set('n', 'x', function() print("real lua function") end)
+--- -- Map "<leader>x" to multiple modes for the current buffer:
+--- vim.keymap.set({'n', 'v'}, '<leader>x', vim.lsp.buf.references, { buffer = true })
+--- -- Map <Tab> to an expression (|:map-<expr>|):
 --- vim.keymap.set('i', '<Tab>', function()
 ---   return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>"
 --- end, { expr = true })
---- -- <Plug> mapping:
+--- -- Map "[%%" to a <Plug> mapping:
 --- vim.keymap.set('n', '[%%', '<Plug>(MatchitNormalMultiBackward)')
 --- ```
 ---
----@param mode string|string[] Mode short-name, see |nvim_set_keymap()|.
----                            Can also be list of modes to create mapping on multiple modes.
+---@param mode string|string[] Mode "short-name" (see |nvim_set_keymap()|), or a list thereof.
 ---@param lhs string           Left-hand side |{lhs}| of the mapping.
 ---@param rhs string|function  Right-hand side |{rhs}| of the mapping, can be a Lua function.
----
 ---@param opts? vim.keymap.set.Opts
+---
 ---@see |nvim_set_keymap()|
 ---@see |maparg()|
 ---@see |mapcheck()|
diff --git a/test/functional/lua/vim_spec.lua b/test/functional/lua/vim_spec.lua
index 1e199818d3..3c65ec664e 100644
--- a/test/functional/lua/vim_spec.lua
+++ b/test/functional/lua/vim_spec.lua
@@ -4043,7 +4043,36 @@ end)
 describe('vim.keymap', function()
   before_each(clear)
 
-  it('can make a mapping', function()
+  it('validates', function()
+    matches(
+      'mode: expected string|table, got number',
+      pcall_err(exec_lua, [[vim.keymap.set(42, 'x', print)]])
+    )
+
+    matches(
+      'rhs: expected string|function, got nil',
+      pcall_err(exec_lua, [[vim.keymap.set('n', 'x')]])
+    )
+
+    matches(
+      'lhs: expected string, got table',
+      pcall_err(exec_lua, [[vim.keymap.set('n', {}, print)]])
+    )
+
+    matches(
+      'opts: expected table, got function',
+      pcall_err(exec_lua, [[vim.keymap.set({}, 'x', 42, function() end)]])
+    )
+
+    matches(
+      'rhs: expected string|function, got number',
+      pcall_err(exec_lua, [[vim.keymap.set('z', 'x', 42)]])
+    )
+
+    matches('Invalid mode shortname: "z"', pcall_err(exec_lua, [[vim.keymap.set('z', 'x', 'y')]]))
+  end)
+
+  it('mapping', function()
     eq(
       0,
       exec_lua [[
@@ -4058,7 +4087,7 @@ describe('vim.keymap', function()
     eq(1, exec_lua [[return GlobalCount]])
   end)
 
-  it('can make an expr mapping', function()
+  it('expr mapping', function()
     exec_lua [[
       vim.keymap.set('n', 'aa', function() return '<Insert>π<C-V><M-π>foo<lt><Esc>' end, {expr = true})
     ]]
@@ -4068,7 +4097,7 @@ describe('vim.keymap', function()
     eq({ 'π<M-π>foo<' }, api.nvim_buf_get_lines(0, 0, -1, false))
   end)
 
-  it('can overwrite a mapping', function()
+  it('overwrite a mapping', function()
     eq(
       0,
       exec_lua [[
@@ -4091,7 +4120,7 @@ describe('vim.keymap', function()
     eq(0, exec_lua [[return GlobalCount]])
   end)
 
-  it('can unmap a mapping', function()
+  it('unmap', function()
     eq(
       0,
       exec_lua [[
@@ -4115,7 +4144,7 @@ describe('vim.keymap', function()
     eq('\nNo mapping found', n.exec_capture('nmap asdf'))
   end)
 
-  it('works with buffer-local mappings', function()
+  it('buffer-local mappings', function()
     eq(
       0,
       exec_lua [[
@@ -4157,7 +4186,7 @@ describe('vim.keymap', function()
     )
   end)
 
-  it('can do <Plug> mappings', function()
+  it('<Plug> mappings', function()
     eq(
       0,
       exec_lua [[