test: improve mapping tests and docs (#19619)

1 files changed, 12 insertions, 11 deletions

diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index dc57841b96..e2f58dba62 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -1411,7 +1411,7 @@ Dictionary nvim_get_mode(void)
 /// Gets a list of global (non-buffer-local) |mapping| definitions.
 ///
 /// @param  mode       Mode short-name ("n", "i", "v", ...)
-/// @returns Array of maparg()-like dictionaries describing mappings.
+/// @returns Array of |maparg()|-like dictionaries describing mappings.
 ///          The "buffer" key is always zero.
 ArrayOf(Dictionary) nvim_get_keymap(uint64_t channel_id, String mode)
   FUNC_API_SINCE(3)
@@ -1423,8 +1423,8 @@ ArrayOf(Dictionary) nvim_get_keymap(uint64_t channel_id, String mode)
 ///
 /// To set a buffer-local mapping, use |nvim_buf_set_keymap()|.
 ///
-/// Unlike |:map|, leading/trailing whitespace is accepted as part of the {lhs}
-/// or {rhs}. Empty {rhs} is |<Nop>|. |keycodes| are replaced as usual.
+/// Unlike |:map|, leading/trailing whitespace is accepted as part of the {lhs} or {rhs}.
+/// Empty {rhs} is |<Nop>|. |keycodes| are replaced as usual.
 ///
 /// Example:
 /// <pre>
@@ -1441,14 +1441,15 @@ ArrayOf(Dictionary) nvim_get_keymap(uint64_t channel_id, String mode)
 ///               or "!" for |:map!|, or empty string for |:map|.
 /// @param  lhs   Left-hand-side |{lhs}| of the mapping.
 /// @param  rhs   Right-hand-side |{rhs}| of the mapping.
-/// @param  opts  Optional parameters map: keys are |:map-arguments|, values
-///               are booleans (default false). Accepts all |:map-arguments| as
-///               keys excluding |<buffer>| but including |noremap| and "desc".
-///               Unknown key is an error. "desc" can be 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()|.
+/// @param  opts  Optional parameters map: keys are |:map-arguments|, values are booleans (default
+///               false). Accepts all |:map-arguments| as keys excluding |<buffer>| but including
+///               |noremap| and "desc". Unknown key is an error.
+///               "desc" can be 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.
+///               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.
 /// @param[out]   err   Error details, if any.
 void nvim_set_keymap(uint64_t channel_id, String mode, String lhs, String rhs, Dict(keymap) *opts,
                      Error *err)