Merge remote-tracking branch 'upstream/master' into aucmd_textputpostaucmd_textputpost

1 files changed, 45 insertions, 53 deletions

diff --git a/runtime/lua/vim/keymap.lua b/runtime/lua/vim/keymap.lua
index ef1c66ea20..bdea95f9ab 100644
--- a/runtime/lua/vim/keymap.lua
+++ b/runtime/lua/vim/keymap.lua
@@ -1,53 +1,41 @@
 local keymap = {}
 
---- Add a new |mapping|.
+--- Adds a new |mapping|.
 --- Examples:
---- <pre>lua
----   -- Can add mapping to Lua functions
----   vim.keymap.set('n', 'lhs', function() print("real lua function") end)
 ---
----   -- Can use it to map multiple modes
----   vim.keymap.set({'n', 'v'}, '<leader>lr', vim.lsp.buf.references, { buffer=true })
+--- ```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:
+--- vim.keymap.set('i', '<Tab>', function()
+---   return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>"
+--- end, { expr = true })
+--- -- <Plug> mapping:
+--- vim.keymap.set('n', '[%%', '<Plug>(MatchitNormalMultiBackward)')
+--- ```
 ---
----   -- Can add mapping for specific buffer
----   vim.keymap.set('n', '<leader>w', "<cmd>w<cr>", { silent = true, buffer = 5 })
----
----   -- Expr mappings
----   vim.keymap.set('i', '<Tab>', function()
----     return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>"
----   end, { expr = true })
----   -- <Plug> mappings
----   vim.keymap.set('n', '[%%', '<Plug>(MatchitNormalMultiBackward)')
---- </pre>
----
---- Note that in a mapping like:
---- <pre>lua
----    vim.keymap.set('n', 'asdf', require('jkl').my_fun)
---- </pre>
----
---- the ``require('jkl')`` gets evaluated during this call in order to access the function.
---- If you want to avoid this cost at startup you can wrap it in a function, for example:
---- <pre>lua
----    vim.keymap.set('n', 'asdf', function() return require('jkl').my_fun() end)
---- </pre>
----
----@param mode string|table    Same mode short names as |nvim_set_keymap()|.
+---@param mode string|table    Mode short-name, see |nvim_set_keymap()|.
 ---                            Can also be list of modes to create mapping on multiple modes.
 ---@param lhs string           Left-hand side |{lhs}| of the mapping.
----@param rhs string|function  Right-hand side |{rhs}| of the mapping. Can also be a Lua function.
---
----@param opts table|nil A table of |:map-arguments|.
----                      + Accepts options accepted by the {opts} parameter in |nvim_set_keymap()|,
----                        with the following notable differences:
----                        - replace_keycodes: Defaults to `true` if "expr" is `true`.
----                        - noremap: Always overridden with the inverse of "remap" (see below).
----                      + In addition to those options, the table accepts the following keys:
----                        - buffer: (number or boolean) Add a mapping to the given buffer.
----                        When `0` or `true`, use the current buffer.
----                        - remap: (boolean) Make the mapping recursive.
----                        This is the inverse of the "noremap" option from |nvim_set_keymap()|.
+---@param rhs string|function  Right-hand side |{rhs}| of the mapping, can be a Lua function.
+---
+---@param opts table|nil Table of |:map-arguments|.
+---                      - Same as |nvim_set_keymap()| {opts}, except:
+---                        - "replace_keycodes" defaults to `true` if "expr" is `true`.
+---                        - "noremap": inverse of "remap" (see below).
+---                      - Also accepts:
+---                        - "buffer": (integer|boolean) Creates buffer-local mapping, `0` or `true`
+---                        for current buffer.
+---                        - "remap": (boolean) Make the mapping recursive. Inverse of "noremap".
 ---                        Defaults to `false`.
 ---@see |nvim_set_keymap()|
+---@see |maparg()|
+---@see |mapcheck()|
+---@see |mapset()|
 function keymap.set(mode, lhs, rhs, opts)
   vim.validate({
     mode = { mode, { 's', 't' } },
@@ -56,7 +44,9 @@ function keymap.set(mode, lhs, rhs, opts)
     opts = { opts, 't', true },
   })
 
-  opts = vim.deepcopy(opts) or {}
+  opts = vim.deepcopy(opts or {})
+
+  ---@cast mode string[]
   mode = type(mode) == 'string' and { mode } or mode
 
   if opts.expr and opts.replace_keycodes ~= false then
@@ -69,7 +59,7 @@ function keymap.set(mode, lhs, rhs, opts)
   else
     -- remaps behavior is opposite of noremap option.
     opts.noremap = not opts.remap
-    opts.remap = nil
+    opts.remap = nil ---@type boolean?
   end
 
   if type(rhs) == 'function' then
@@ -78,8 +68,8 @@ function keymap.set(mode, lhs, rhs, opts)
   end
 
   if opts.buffer then
-    local bufnr = opts.buffer == true and 0 or opts.buffer
-    opts.buffer = nil
+    local bufnr = opts.buffer == true and 0 or opts.buffer --[[@as integer]]
+    opts.buffer = nil ---@type integer?
     for _, m in ipairs(mode) do
       vim.api.nvim_buf_set_keymap(bufnr, m, lhs, rhs, opts)
     end
@@ -93,14 +83,16 @@ end
 
 --- Remove an existing mapping.
 --- Examples:
---- <pre>lua
----   vim.keymap.del('n', 'lhs')
 ---
----   vim.keymap.del({'n', 'i', 'v'}, '<leader>w', { buffer = 5 })
---- </pre>
+--- ```lua
+--- vim.keymap.del('n', 'lhs')
+---
+--- vim.keymap.del({'n', 'i', 'v'}, '<leader>w', { buffer = 5 })
+--- ```
+---
 ---@param opts table|nil A table of optional arguments:
----                      - buffer: (number or boolean) Remove a mapping from the given buffer.
----                      When "true" or 0, use the current buffer.
+---                      - "buffer": (integer|boolean) Remove a mapping from the given buffer.
+---                        When `0` or `true`, use the current buffer.
 ---@see |vim.keymap.set()|
 ---
 function keymap.del(modes, lhs, opts)
@@ -113,9 +105,9 @@ function keymap.del(modes, lhs, opts)
   opts = opts or {}
   modes = type(modes) == 'string' and { modes } or modes
 
-  local buffer = false
+  local buffer = false ---@type false|integer
   if opts.buffer ~= nil then
-    buffer = opts.buffer == true and 0 or opts.buffer
+    buffer = opts.buffer == true and 0 or opts.buffer --[[@as integer]]
   end
 
   if buffer == false then