From 6752f1005d26c93a033d856a60b7b296f3e51634 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Wed, 14 Dec 2022 19:58:18 +0100 Subject: docs: naming conventions, guidelines close #21063 --- runtime/lua/vim/keymap.lua | 50 ++++++++++++++++------------------------------ 1 file changed, 17 insertions(+), 33 deletions(-) (limited to 'runtime/lua/vim/keymap.lua') diff --git a/runtime/lua/vim/keymap.lua b/runtime/lua/vim/keymap.lua index ef1c66ea20..911b584c14 100644 --- a/runtime/lua/vim/keymap.lua +++ b/runtime/lua/vim/keymap.lua @@ -1,51 +1,35 @@ local keymap = {} ---- Add a new |mapping|. +--- Adds a new |mapping|. --- Examples: --- 
lua
----   -- Can add mapping to Lua functions
+---   -- Map to a Lua function:
 ---   vim.keymap.set('n', 'lhs', function() print("real lua function") end)
----
----   -- Can use it to map multiple modes
+---   -- Map to multiple modes:
 ---   vim.keymap.set({'n', 'v'}, 'lr', vim.lsp.buf.references, { buffer=true })
----
----   -- Can add mapping for specific buffer
+---   -- Buffer-local mapping:
 ---   vim.keymap.set('n', 'w', "w", { silent = true, buffer = 5 })
----
----   -- Expr mappings
+---   -- Expr mapping:
 ---   vim.keymap.set('i', '', function()
 ---     return vim.fn.pumvisible() == 1 and "" or ""
 ---   end, { expr = true })
----   --  mappings
+---   --  mapping:
 ---   vim.keymap.set('n', '[%%', '(MatchitNormalMultiBackward)')
 ---
--- ---- Note that in a mapping like: ---- 
lua
----    vim.keymap.set('n', 'asdf', require('jkl').my_fun)
----
---- ---- 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: ---- 
lua
----    vim.keymap.set('n', 'asdf', function() return require('jkl').my_fun() end)
----
---- ----@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" number|boolean Creates buffer-local mapping, `0` or `true` +--- for current buffer. +--- - remap: (boolean) Make the mapping recursive. Inverses "noremap". --- Defaults to `false`. ---@see |nvim_set_keymap()| function keymap.set(mode, lhs, rhs, opts) -- cgit From 7154f0c98619d0789618f370a6c7f81ee1775469 Mon Sep 17 00:00:00 2001 From: Jonas Strittmatter <40792180+smjonas@users.noreply.github.com> Date: Sat, 10 Jun 2023 03:37:05 +0200 Subject: docs: fix typos (#23917) --- runtime/lua/vim/keymap.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'runtime/lua/vim/keymap.lua') diff --git a/runtime/lua/vim/keymap.lua b/runtime/lua/vim/keymap.lua index 911b584c14..0d7fc3b1ec 100644 --- a/runtime/lua/vim/keymap.lua +++ b/runtime/lua/vim/keymap.lua @@ -6,7 +6,7 @@ local keymap = {} --- -- 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'}, 'lr', vim.lsp.buf.references, { buffer=true }) +--- vim.keymap.set({'n', 'v'}, 'lr', vim.lsp.buf.references, { buffer = true }) --- -- Buffer-local mapping: --- vim.keymap.set('n', 'w', "w", { silent = true, buffer = 5 }) --- -- Expr mapping: -- cgit From 0eb02ea90a5a7c2e35bfcf99b701a28ff2901b4b Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Mon, 12 Jun 2023 20:08:08 +0800 Subject: docs: various clarifications (#23999) Close #18907 Close #20314 Close #23749 --- runtime/lua/vim/keymap.lua | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'runtime/lua/vim/keymap.lua') diff --git a/runtime/lua/vim/keymap.lua b/runtime/lua/vim/keymap.lua index 0d7fc3b1ec..9dbc65afe8 100644 --- a/runtime/lua/vim/keymap.lua +++ b/runtime/lua/vim/keymap.lua @@ -27,9 +27,9 @@ local keymap = {} --- - "replace_keycodes" defaults to `true` if "expr" is `true`. --- - "noremap": inverse of "remap" (see below). --- - Also accepts: ---- - "buffer" number|boolean Creates buffer-local mapping, `0` or `true` +--- - "buffer": (number|boolean) Creates buffer-local mapping, `0` or `true` --- for current buffer. ---- - remap: (boolean) Make the mapping recursive. Inverses "noremap". +--- - "remap": (boolean) Make the mapping recursive. Inverse of "noremap". --- Defaults to `false`. ---@see |nvim_set_keymap()| function keymap.set(mode, lhs, rhs, opts) @@ -83,8 +83,8 @@ end --- vim.keymap.del({'n', 'i', 'v'}, '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": (number|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) -- cgit From a3f4598226c4d01e4fbc41181a1ad21793862fe3 Mon Sep 17 00:00:00 2001 From: Mathias Fußenegger Date: Thu, 13 Jul 2023 14:43:36 +0200 Subject: docs(lua): adds links to related keymap functions to keymap.set (#24337) Might help with discovery, given that there is no `keymap.get()` --- runtime/lua/vim/keymap.lua | 3 +++ 1 file changed, 3 insertions(+) (limited to 'runtime/lua/vim/keymap.lua') diff --git a/runtime/lua/vim/keymap.lua b/runtime/lua/vim/keymap.lua index 9dbc65afe8..2b55ddc787 100644 --- a/runtime/lua/vim/keymap.lua +++ b/runtime/lua/vim/keymap.lua @@ -32,6 +32,9 @@ local keymap = {} --- - "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' } }, -- cgit From 2e92065686f62851318150a315591c30b8306a4b Mon Sep 17 00:00:00 2001 From: Gregory Anders <8965202+gpanders@users.noreply.github.com> Date: Thu, 14 Sep 2023 08:23:01 -0500 Subject: docs: replace 
 with ``` (#25136)

---
 runtime/lua/vim/keymap.lua | 39 +++++++++++++++++++++------------------
 1 file changed, 21 insertions(+), 18 deletions(-)

(limited to 'runtime/lua/vim/keymap.lua')

diff --git a/runtime/lua/vim/keymap.lua b/runtime/lua/vim/keymap.lua
index 2b55ddc787..df593be097 100644
--- a/runtime/lua/vim/keymap.lua
+++ b/runtime/lua/vim/keymap.lua
@@ -2,20 +2,21 @@ local keymap = {}
 
 --- 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'}, 'lr', vim.lsp.buf.references, { buffer = true })
----   -- Buffer-local mapping:
----   vim.keymap.set('n', 'w', "w", { silent = true, buffer = 5 })
----   -- Expr mapping:
----   vim.keymap.set('i', '', function()
----     return vim.fn.pumvisible() == 1 and "" or ""
----   end, { expr = true })
----   --  mapping:
----   vim.keymap.set('n', '[%%', '(MatchitNormalMultiBackward)')
---- 

+---
+--- ```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'}, 'lr', vim.lsp.buf.references, { buffer = true })
+--- -- Buffer-local mapping:
+--- vim.keymap.set('n', 'w', "w", { silent = true, buffer = 5 })
+--- -- Expr mapping:
+--- vim.keymap.set('i', '', function()
+---   return vim.fn.pumvisible() == 1 and "" or ""
+--- end, { expr = true })
+--- --  mapping:
+--- vim.keymap.set('n', '[%%', '(MatchitNormalMultiBackward)')
+--- ```
 ---
 ---@param mode string|table    Mode short-name, see |nvim_set_keymap()|.
 ---                            Can also be list of modes to create mapping on multiple modes.
@@ -80,11 +81,13 @@ end
 
 --- Remove an existing mapping.
 --- Examples:
---- 
lua
----   vim.keymap.del('n', 'lhs')
 ---
----   vim.keymap.del({'n', 'i', 'v'}, 'w', { buffer = 5 })
---- 

+--- ```lua
+--- vim.keymap.del('n', 'lhs')
+---
+--- vim.keymap.del({'n', 'i', 'v'}, 'w', { buffer = 5 })
+--- ```
+---
 ---@param opts table|nil A table of optional arguments:
 ---                      - "buffer": (number|boolean) Remove a mapping from the given buffer.
 ---                        When `0` or `true`, use the current buffer.
-- 
cgit 


From bc0bf9d030bbcb01db69c44cf88b95ca41dd3065 Mon Sep 17 00:00:00 2001
From: Maria José Solano 
Date: Wed, 20 Sep 2023 19:03:40 -0700
Subject: docs: fix type warnings

---
 runtime/lua/vim/keymap.lua | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

(limited to 'runtime/lua/vim/keymap.lua')

diff --git a/runtime/lua/vim/keymap.lua b/runtime/lua/vim/keymap.lua
index df593be097..bdea95f9ab 100644
--- a/runtime/lua/vim/keymap.lua
+++ b/runtime/lua/vim/keymap.lua
@@ -28,7 +28,7 @@ local keymap = {}
 ---                        - "replace_keycodes" defaults to `true` if "expr" is `true`.
 ---                        - "noremap": inverse of "remap" (see below).
 ---                      - Also accepts:
----                        - "buffer": (number|boolean) Creates buffer-local mapping, `0` or `true`
+---                        - "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`.
@@ -44,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
@@ -57,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
@@ -66,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
@@ -89,7 +91,7 @@ end
 --- ```
 ---
 ---@param opts table|nil A table of optional arguments:
----                      - "buffer": (number|boolean) Remove a mapping from the given buffer.
+---                      - "buffer": (integer|boolean) Remove a mapping from the given buffer.
 ---                        When `0` or `true`, use the current buffer.
 ---@see |vim.keymap.set()|
 ---
@@ -103,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
-- 
cgit