docs: various clarifications (#23999)

Close #18907
Close #20314
Close #23749

7 files changed, 18 insertions, 33 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 748a8ba3bb..1732c24f2f 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -1495,7 +1495,7 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts})             *nvim_set_keymap()*
                 except |<buffer>|, values are booleans (default false). Also:
                 • "noremap" non-recursive mapping |:noremap|
                 • "desc" human-readable description.
-                • "callback" Lua function called when the mapping is executed.
+                • "callback" Lua function called in place of {rhs}.
                 • "replace_keycodes" (boolean) When "expr" is true, replace
                   keycodes in the resulting string (see
                   |nvim_replace_termcodes()|). Returning nil from the Lua
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 7cd13926c7..737aa91e97 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -867,21 +867,6 @@ vim.schedule({callback})                                      *vim.schedule()*
     Schedules {callback} to be invoked soon by the main event-loop. Useful
     to avoid |textlock| or other temporary restrictions.
 
-
-vim.defer_fn({fn}, {timeout})                                   *vim.defer_fn*
-    Defers calling {fn} until {timeout} ms passes. Use to do a one-shot timer
-    that calls {fn}.
-
-    Note: The {fn} is |vim.schedule_wrap()|ped automatically, so API functions are
-    safe to call.
-
-    Parameters: ~
-      • {fn}        Callback to call once {timeout} expires
-      • {timeout}   Time in ms to wait before calling {fn}
-
-    Returns: ~
-        |vim.uv|.new_timer() object
-
 vim.wait({time} [, {callback}, {interval}, {fast_only}])          *vim.wait()*
     Wait for {time} in milliseconds until {callback} returns `true`.
 
@@ -1376,10 +1361,10 @@ connection_failure_errmsg({consequence})
     TODO: Documentation
 
 defer_fn({fn}, {timeout})                                     *vim.defer_fn()*
-    Defers calling `fn` until `timeout` ms passes.
+    Defers calling {fn} until {timeout} ms passes.
 
-    Use to do a one-shot timer that calls `fn` Note: The {fn} is |vim.schedule_wrap()|ped automatically, so API functions
-    are safe to call.
+    Use to do a one-shot timer that calls {fn} Note: The {fn} is
+    |vim.schedule_wrap()|ped automatically, so API functions are safe to call.
 
     Parameters: ~
       • {fn}       (function) Callback to call once `timeout` expires
@@ -2551,8 +2536,8 @@ del({modes}, {lhs}, {opts})                                 *vim.keymap.del()*
 
     Parameters: ~
       • {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 also: ~
       • |vim.keymap.set()|
@@ -2586,9 +2571,9 @@ set({mode}, {lhs}, {rhs}, {opts})                           *vim.keymap.set()*
                   • "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
+                  • "buffer": (number|boolean) Creates buffer-local mapping,
+                    `0` or `true` for current buffer.
+                  • "remap": (boolean) Make the mapping recursive. Inverse of
                     "noremap". Defaults to `false`.
 
     See also: ~
diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt
index 9613092ba9..25ab91b89e 100644
--- a/runtime/doc/map.txt
+++ b/runtime/doc/map.txt
@@ -1391,7 +1391,7 @@ completion can be enabled:
 	-complete=highlight	highlight groups
 	-complete=history	:history suboptions
 	-complete=locale	locale names (as output of locale -a)
-	-complete=lua		Lua expression
+	-complete=lua		Lua expression |:lua|
 	-complete=mapclear	buffer argument
 	-complete=mapping	mapping name
 	-complete=menu		menus
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 2c7ca487e6..ab1b2056a2 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -762,7 +762,7 @@ TUI:
 
 Cscope:
                                                                       *cscope*
-  Cscope support has been removed in favour of LSP based solutions.
+  Cscope support has been removed in favour of plugin-based solutions.
 
 Hardcopy:
                                                                      *hardcopy*
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index 1c7eb30b03..1de2ade1a1 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -534,9 +534,9 @@ function vim.region(bufnr, pos1, pos2, regtype, inclusive)
   return region
 end
 
---- Defers calling `fn` until `timeout` ms passes.
+--- Defers calling {fn} until {timeout} ms passes.
 ---
---- Use to do a one-shot timer that calls `fn`
+--- Use to do a one-shot timer that calls {fn}
 --- Note: The {fn} is |vim.schedule_wrap()|ped automatically, so API functions are
 --- safe to call.
 ---@param fn function Callback to call once `timeout` expires
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'}, '<leader>w', { buffer = 5 })
 --- </pre>
 ---@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)
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 62b4fd9764..368bb866d7 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -1427,7 +1427,7 @@ ArrayOf(Dictionary) nvim_get_keymap(String mode)
 ///               values are booleans (default false). Also:
 ///               - "noremap" non-recursive mapping |:noremap|
 ///               - "desc" human-readable description.
-///               - "callback" Lua function called when the mapping is executed.
+///               - "callback" Lua function called in place of {rhs}.
 ///               - "replace_keycodes" (boolean) When "expr" is true, replace keycodes in the
 ///                 resulting string (see |nvim_replace_termcodes()|). Returning nil from the Lua
 ///                 "callback" is equivalent to returning an empty string.