From 0a049c322fda5f2bb124429086c2713ff99c7142 Mon Sep 17 00:00:00 2001
From: zeertzjq <zeertzjq@outlook.com>
Date: Tue, 2 Aug 2022 11:13:22 +0800
Subject: test: improve mapping tests and docs (#19619)

---
 runtime/doc/api.txt        | 13 ++++++++-----
 runtime/doc/lua.txt        |  4 +---
 runtime/lua/vim/keymap.lua |  6 ++----
 3 files changed, 11 insertions(+), 12 deletions(-)

(limited to 'runtime')

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index aaafa21a59..827d0318ab 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -974,7 +974,7 @@ nvim_get_keymap({mode})                                    *nvim_get_keymap()*
                     {mode}  Mode short-name ("n", "i", "v", ...)
 
                 Return: ~
-                    Array of maparg()-like dictionaries describing mappings.
+                    Array of |maparg()|-like dictionaries describing mappings.
                     The "buffer" key is always zero.
 
 nvim_get_mark({name}, {opts})                                *nvim_get_mark()*
@@ -1508,9 +1508,12 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts})             *nvim_set_keymap()*
                             used to give a description to the mapping. When
                             called from Lua, also accepts a "callback" key
                             that takes a Lua function to call when the mapping
-                            is executed. "replace_keycodes" can be used with
-                            "expr" to replace keycodes, see
-                            |nvim_replace_termcodes()|.
+                            is executed. When "expr" is true,
+                            "replace_keycodes" (boolean) can be used to
+                            replace keycodes in the resulting string (see
+                            |nvim_replace_termcodes()|), and a Lua callback
+                            returning `nil` is equivalent to returning an
+                            empty string.
 
 nvim_set_var({name}, {value})                                 *nvim_set_var()*
                 Sets a global (g:) variable.
@@ -2299,7 +2302,7 @@ nvim_buf_get_keymap({buffer}, {mode})                  *nvim_buf_get_keymap()*
                     {buffer}  Buffer handle, or 0 for current buffer
 
                 Return: ~
-                    Array of maparg()-like dictionaries describing mappings.
+                    Array of |maparg()|-like dictionaries describing mappings.
                     The "buffer" key holds the associated buffer handle.
 
                                                         *nvim_buf_get_lines()*
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 6dfb0b5791..c9505429c6 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2218,9 +2218,7 @@ set({mode}, {lhs}, {rhs}, {opts})                           *vim.keymap.set()*
                             create mapping on multiple modes.
                     {lhs}   (string) Left-hand side |{lhs}| of the mapping.
                     {rhs}   string|function Right-hand side |{rhs}| of the
-                            mapping. Can also be a Lua function. If a Lua
-                            function and `opts.expr == true`, returning `nil`
-                            is equivalent to an empty string.
+                            mapping. Can also be a Lua function.
                     {opts}  (table) A table of |:map-arguments| such as
                             "silent". In addition to the options listed in
                             |nvim_set_keymap()|, this table also accepts the
diff --git a/runtime/lua/vim/keymap.lua b/runtime/lua/vim/keymap.lua
index 3592855606..0549f63180 100644
--- a/runtime/lua/vim/keymap.lua
+++ b/runtime/lua/vim/keymap.lua
@@ -31,12 +31,10 @@ local keymap = {}
 ---    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    Same mode short names as |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 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.
----                            If a Lua function and `opts.expr == true`, returning `nil` is
----                            equivalent to an empty string.
 --
 ---@param opts table A table of |:map-arguments| such as "silent". In addition to the options
 ---                  listed in |nvim_set_keymap()|, this table also accepts the following keys:
-- 
cgit