neovim

commit bef68ba266038b94a532ce76e315dd71089939f3
parent 6228acb74f94ead074627c152faeed1b17f4e7d9
Author: Bryan Turns <95263942+BryanTurns@users.noreply.github.com>
Date:   Sat, 20 Dec 2025 18:26:44 -0600

docs(lua): iInconsistent vim.keymap param name #37026

Problem: vim.keymap.del has 'modes' as it's first argument while vim.keymap.set
has 'mode' as it's first argument despite both 'mode' and 'modes' taking in the
same type input of String or String[].

Solution: Updated vim.keymap.set docs to refer to it's first argument
as 'modes'.
Diffstat:
M
runtime/doc/lua.txt
 | 
28
++++++++++++++--------------
M
runtime/lua/vim/keymap.lua
 | 
14
+++++++-------
M
test/functional/lua/vim_spec.lua
 | 
2
+-

3 files changed, 22 insertions(+), 22 deletions(-)
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
@@ -3440,7 +3440,7 @@ vim.keymap.del({modes}, {lhs}, {opts})                      *vim.keymap.del()*
     See also: ~
       • |vim.keymap.set()|
 
-vim.keymap.set({mode}, {lhs}, {rhs}, {opts})                *vim.keymap.set()*
+vim.keymap.set({modes}, {lhs}, {rhs}, {opts})               *vim.keymap.set()*
     Defines a |mapping| of |keycodes| to a function or keycodes.
 
     Examples: >lua
@@ -3469,20 +3469,20 @@ vim.keymap.set({mode}, {lhs}, {rhs}, {opts})                *vim.keymap.set()*
 <
 
     Parameters: ~
-      • {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.
-      • {opts}  (`table?`) Table of |:map-arguments|. Same as
-                |nvim_set_keymap()| {opts}, except:
-                • {replace_keycodes} defaults to `true` if "expr" is `true`.
+      • {modes}  (`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.
+      • {opts}   (`table?`) Table of |:map-arguments|. Same as
+                 |nvim_set_keymap()| {opts}, except:
+                 • {replace_keycodes} defaults to `true` if "expr" is `true`.
 
-                Also accepts:
-                • {buffer}? (`integer|boolean`) Creates buffer-local mapping,
-                  `0` or `true` for current buffer.
-                • {remap}? (`boolean`, default: `false`) Make the mapping
-                  recursive. Inverse of {noremap}.
+                 Also accepts:
+                 • {buffer}? (`integer|boolean`) Creates buffer-local mapping,
+                   `0` or `true` for current buffer.
+                 • {remap}? (`boolean`, default: `false`) Make the mapping
+                   recursive. Inverse of {noremap}.
 
     See also: ~
       • |nvim_set_keymap()|
diff --git a/runtime/lua/vim/keymap.lua b/runtime/lua/vim/keymap.lua
@@ -44,7 +44,7 @@ local keymap = {}
 --- end)
 --- ```
 ---
----@param mode string|string[] Mode "short-name" (see |nvim_set_keymap()|), or a list thereof.
+---@param modes 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
@@ -53,16 +53,16 @@ local keymap = {}
 ---@see |maparg()|
 ---@see |mapcheck()|
 ---@see |mapset()|
-function keymap.set(mode, lhs, rhs, opts)
-  vim.validate('mode', mode, { 'string', 'table' })
+function keymap.set(modes, lhs, rhs, opts)
+  vim.validate('modes', modes, { 'string', 'table' })
   vim.validate('lhs', lhs, 'string')
   vim.validate('rhs', rhs, { 'string', 'function' })
   vim.validate('opts', opts, 'table', true)
 
   opts = vim.deepcopy(opts or {}, true)
 
-  ---@cast mode string[]
-  mode = type(mode) == 'string' and { mode } or mode
+  ---@cast modes string[]
+  modes = type(modes) == 'string' and { modes } or modes
 
   if opts.expr and opts.replace_keycodes ~= false then
     opts.replace_keycodes = true
@@ -85,12 +85,12 @@ function keymap.set(mode, lhs, rhs, opts)
   if opts.buffer then
     local bufnr = opts.buffer == true and 0 or opts.buffer --[[@as integer]]
     opts.buffer = nil ---@type integer?
-    for _, m in ipairs(mode) do
+    for _, m in ipairs(modes) do
       vim.api.nvim_buf_set_keymap(bufnr, m, lhs, rhs, opts)
     end
   else
     opts.buffer = nil
-    for _, m in ipairs(mode) do
+    for _, m in ipairs(modes) do
       vim.api.nvim_set_keymap(m, lhs, rhs, opts)
     end
   end
diff --git a/test/functional/lua/vim_spec.lua b/test/functional/lua/vim_spec.lua
@@ -3042,7 +3042,7 @@ describe('vim.keymap', function()
 
   it('validates', function()
     matches(
-      'mode: expected string|table, got number',
+      'modes: expected string|table, got number',
       pcall_err(exec_lua, [[vim.keymap.set(42, 'x', print)]])
     )