Merge #37830 docs

18 files changed, 141 insertions, 125 deletions

diff --git a/runtime/lua/vim/_core/defaults.lua b/runtime/lua/vim/_core/defaults.lua
index e923e8934c..9b9ab01b52 100644
--- a/runtime/lua/vim/_core/defaults.lua
+++ b/runtime/lua/vim/_core/defaults.lua
@@ -445,15 +445,15 @@ do
     end, { expr = true, desc = 'Add empty line below cursor' })
   end
 
-  --- incremental treesitter selection mappings (+ lsp fallback)
+  --- "Incremental selection" mappings (treesitter + LSP fallback).
   do
     vim.keymap.set({ 'x' }, '[n', function()
       require 'vim.treesitter._select'.select_prev(vim.v.count1)
-    end, { desc = 'Select previous treesitter node' })
+    end, { desc = 'Select previous node' })
 
     vim.keymap.set({ 'x' }, ']n', function()
       require 'vim.treesitter._select'.select_next(vim.v.count1)
-    end, { desc = 'Select next treesitter node' })
+    end, { desc = 'Select next node' })
 
     vim.keymap.set({ 'x', 'o' }, 'an', function()
       if vim.treesitter.get_parser(nil, nil, { error = false }) then
@@ -461,7 +461,7 @@ do
       else
         vim.lsp.buf.selection_range(vim.v.count1)
       end
-    end, { desc = 'Select parent treesitter node or outer incremental lsp selections' })
+    end, { desc = 'Select parent (outer) node' })
 
     vim.keymap.set({ 'x', 'o' }, 'in', function()
       if vim.treesitter.get_parser(nil, nil, { error = false }) then
@@ -469,7 +469,7 @@ do
       else
         vim.lsp.buf.selection_range(-vim.v.count1)
       end
-    end, { desc = 'Select child treesitter node or inner incremental lsp selections' })
+    end, { desc = 'Select child (inner) node' })
   end
 end
 
diff --git a/runtime/lua/vim/_core/shared.lua b/runtime/lua/vim/_core/shared.lua
index 1f01b70f2a..da50338d01 100644
--- a/runtime/lua/vim/_core/shared.lua
+++ b/runtime/lua/vim/_core/shared.lua
@@ -360,7 +360,7 @@ local function key_fn(v, key)
   return key and key(v) or v
 end
 
---- Removes duplicate values from a list-like table in-place.
+--- Removes duplicate values from a |lua-list| in-place.
 ---
 --- Only the first occurrence of each value is kept.
 --- The operation is performed in-place and the input table is modified.
@@ -383,6 +383,7 @@ end
 --- -- t is now { {id=1}, {id=2} }
 --- ```
 ---
+--- @since 14
 --- @generic T
 --- @param t T[]
 --- @param key? fun(x: T): any Optional hash function to determine uniqueness of values
@@ -482,8 +483,8 @@ local function upper_bound(t, val, lo, hi, key)
   return lo
 end
 
---- Search for a position in a sorted list {t}
---- where {val} can be inserted while keeping the list sorted.
+--- Search for a position in a sorted |lua-list| {t} where {val} can be inserted while keeping the
+--- list sorted.
 ---
 --- Use {bound} to determine whether to return the first or the last position,
 --- defaults to "lower", i.e., the first position.
@@ -514,6 +515,7 @@ end
 ---   print(t[i]) -- { 3, 3, 3 }
 --- end
 --- ```
+---@since 14
 ---@generic T
 ---@param t T[] A comparable list.
 ---@param val T The value to search.
diff --git a/runtime/lua/vim/_core/ui2.lua b/runtime/lua/vim/_core/ui2.lua
index debd1feac5..1414eb75e7 100644
--- a/runtime/lua/vim/_core/ui2.lua
+++ b/runtime/lua/vim/_core/ui2.lua
@@ -1,38 +1,37 @@
 --- @brief
 ---
----WARNING: This is an experimental interface intended to replace the message
----grid in the TUI.
+--- WARNING: This is an experimental feature intended to replace the builtin message + cmdline
+--- presentation layer.
 ---
----To enable the experimental UI (default opts shown):
----```lua
----require('vim._core.ui2').enable({
----  enable = true, -- Whether to enable or disable the UI.
----  msg = { -- Options related to the message module.
----    ---@type 'cmd'|'msg' Default message target, either in the
----    ---cmdline or in a separate ephemeral message window.
----    ---@type string|table<string, 'cmd'|'msg'|'pager'> Default message target
----    or table mapping |ui-messages| kinds and triggers to a target.
----    targets = 'cmd',
----    timeout = 4000, -- Time a message is visible in the message window.
----  },
----})
----```
+--- To enable this feature (default opts shown):
+--- ```lua
+--- require('vim._core.ui2').enable({
+---   enable = true, -- Whether to enable or disable the UI.
+---   msg = { -- Options related to the message module.
+---     ---@type 'cmd'|'msg' Default message target, either in the
+---     ---cmdline or in a separate ephemeral message window.
+---     ---@type string|table<string, 'cmd'|'msg'|'pager'> Default message target
+---     ---or table mapping |ui-messages| kinds and triggers to a target.
+---     targets = 'cmd',
+---     timeout = 4000, -- Time a message is visible in the message window.
+---   },
+--- })
+--- ```
 ---
----There are four separate window types used by this interface:
----- "cmd": The cmdline window; also used for 'showcmd', 'showmode', 'ruler', and
----  messages if 'cmdheight' > 0.
----- "msg": The message window; used for messages when 'cmdheight' == 0.
----- "pager": The pager window; used for |:messages| and certain messages
----   that should be shown in full.
----- "dialog": The dialog window; used for prompt messages that expect user input.
+--- There are four special windows/buffers for presenting messages and cmdline:
+--- - "cmd": Cmdline. Also used for 'showcmd', 'showmode', 'ruler', and messages if 'cmdheight' > 0.
+--- - "msg": Message window, shows messages when 'cmdheight' == 0.
+--- - "pager": Pager window, shows |:messages| and certain messages that are never "collapsed".
+--- - "dialog": Dialog window, shows modal prompts that expect user input.
 ---
----These four windows are assigned the "cmd", "msg", "pager" and "dialog"
----'filetype' respectively. Use a |FileType| autocommand to configure any local
----options for these windows and their respective buffers.
+--- The buffer 'filetype' is to the above-listed id ("cmd", "msg", …). Handle the |FileType| event
+--- to configure any local options for these windows and their respective buffers.
 ---
----Rather than a |hit-enter-prompt|, messages shown in the cmdline area that do
----not fit are appended with a `[+x]` "spill" indicator, where `x` indicates the
----spilled lines. To see the full message, the |g<| command can be used.
+--- Unlike the legacy |hit-enter| prompt, messages that overflow the cmdline area are instead
+--- "collapsed", followed by a `[+x]` "spill" indicator, where `x` indicates the spilled lines. To
+--- see the full messages, do either:
+--- - ENTER immediately after a message from interactive |:| cmdline.
+--- - |g<| at any time.
 
 local api = vim.api
 local M = {
diff --git a/runtime/lua/vim/_meta.lua b/runtime/lua/vim/_meta.lua
index 02f886cf96..9ac6ceeb77 100644
--- a/runtime/lua/vim/_meta.lua
+++ b/runtime/lua/vim/_meta.lua
@@ -20,6 +20,7 @@ vim.iter = require('vim.iter')
 vim.keymap = require('vim.keymap')
 vim.loader = require('vim.loader')
 vim.lsp = require('vim.lsp')
+vim.net = require('vim.net')
 vim.pack = require('vim.pack')
 vim.pos = require('vim.pos')
 vim.range = require('vim.range')
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index 9b7bec6678..1197e8620b 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -1299,15 +1299,15 @@ function vim.api.nvim_get_autocmds(opts) end
 ---      - "stderr"     stderr of this Nvim instance
 ---      - "socket"     TCP/IP socket or named pipe
 ---      - "job"        Job with communication over its stdio.
---- -  "mode"    How data received on the channel is interpreted.
+--- - "mode"     How data received on the channel is interpreted.
 ---      - "bytes"      Send and receive raw bytes.
 ---      - "terminal"   |terminal| instance interprets ASCII sequences.
 ---      - "rpc"        |RPC| communication on the channel is active.
---- -  "pty"     (optional) Name of pseudoterminal. On a POSIX system this is a device path like
+--- - "pty"      (optional) Name of pseudoterminal. On a POSIX system this is a device path like
 ---              "/dev/pts/1". If unknown, the key will still be present if a pty is used (e.g.
 ---              for conpty on Windows).
---- -  "buffer"  (optional) Buffer connected to |terminal| instance.
---- -  "client"  (optional) Info about the peer (client on the other end of the channel), as set
+--- - "buffer"   (optional) Buffer connected to |terminal| instance.
+--- - "client"   (optional) Info about the peer (client on the other end of the channel), as set
 ---              by |nvim_set_client_info()|.
 --- - "exitcode" (optional) Exit code of the |terminal| process.
 ---
@@ -1703,26 +1703,19 @@ function vim.api.nvim_notify(msg, log_level, opts) end
 --- @return integer # Channel id, or 0 on error
 function vim.api.nvim_open_term(buffer, opts) end
 
---- Opens a new split window, or a floating window if `relative` is specified,
---- or an external window (managed by the UI) if `external` is specified.
+--- Opens a new split window, floating window, or external window.
 ---
---- Floats are windows that are drawn above the split layout, at some anchor
---- position in some other window. Floats can be drawn internally or by external
---- GUI with the `ui-multigrid` extension. External windows are only supported
---- with multigrid GUIs, and are displayed as separate top-level windows.
----
---- For a general overview of floats, see `api-floatwin`.
----
---- The `width` and `height` of the new window must be specified when opening
---- a floating window, but are optional for normal windows.
----
---- If `relative` and `external` are omitted, a normal "split" window is created.
---- The `win` property determines which window will be split. If no `win` is
---- provided or `win == 0`, a window will be created adjacent to the current window.
---- If -1 is provided, a top-level split will be created. `vertical` and `split` are
---- only valid for normal windows, and are used to control split direction. For `vertical`,
---- the exact direction is determined by 'splitright' and 'splitbelow'.
---- Split windows cannot have `bufpos`, `row`, `col`, `border`, `title`, `footer` properties.
+--- - Specify `relative` to create a floating window. Floats are drawn over the split layout,
+---   relative to a position in some other window. See `api-floatwin`.
+---   - Floats must specify `width` and `height`.
+--- - Specify `external` to create an external window. External windows are displayed as separate
+---   top-level windows managed by the `ui-multigrid` UI (not Nvim).
+--- - If `relative` and `external` are omitted, a normal "split" window is created.
+---   - The `win` key decides which window to split. If nil or 0, the split will be adjacent to
+---     the current window. If -1, a top-level split will be created.
+---   - Use `vertical` and `split` to control split direction. For `vertical`, the exact direction
+---     is determined by 'splitright' and 'splitbelow'.
+---   - Split windows cannot have `bufpos`, `row`, `col`, `border`, `title`, `footer`.
 ---
 --- With relative=editor (row=0,col=0) refers to the top-left corner of the
 --- screen-grid and (row=Lines-1,col=Columns-1) refers to the bottom-right
@@ -2492,11 +2485,11 @@ function vim.api.nvim_win_is_valid(window) end
 --- @param buffer integer Buffer id
 function vim.api.nvim_win_set_buf(window, buffer) end
 
---- Reconfigures the layout of a window.
+--- Reconfigures the layout and properties of a window.
 ---
---- - Absent (`nil`) keys will not be changed.
---- - `row` / `col` / `relative` must be reconfigured together.
---- - Cannot be used to move the last window in a tabpage to a different one.
+--- - Updates only the given keys; unspecified (`nil`) keys will not be changed.
+--- - Keys `row` / `col` / `relative` must be specified together.
+--- - Cannot move the last window in a tabpage to a different one.
 ---
 --- Example: to convert a floating window to a "normal" split window, specify the `win` field:
 ---
diff --git a/runtime/lua/vim/_meta/builtin_types.lua b/runtime/lua/vim/_meta/builtin_types.lua
index 47a5242cbb..581926d5f3 100644
--- a/runtime/lua/vim/_meta/builtin_types.lua
+++ b/runtime/lua/vim/_meta/builtin_types.lua
@@ -60,6 +60,7 @@
 --- @field botline integer
 --- @field bufnr integer
 --- @field height integer
+--- @field leftcol integer
 --- @field loclist integer
 --- @field quickfix integer
 --- @field tabnr integer
diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua
index 177c77b8eb..4b532cf34e 100644
--- a/runtime/lua/vim/_meta/options.lua
+++ b/runtime/lua/vim/_meta/options.lua
@@ -3159,6 +3159,7 @@ vim.go.gp = vim.go.grepprg
 ---
 --- ```vim
 ---     highlight Cursor gui=reverse guifg=NONE guibg=NONE
+---     " Note: gui=reverse overrides colors.
 ---     highlight Cursor gui=NONE guifg=bg guibg=fg
 --- ```
 ---
@@ -3240,7 +3241,7 @@ vim.go.gcr = vim.go.guicursor
 ---
 ---
 --- @type string
-vim.o.guifont = "Source Code Pro,DejaVu Sans Mono,Courier New,monospace"
+vim.o.guifont = "DFLT_GFN"
 vim.o.gfn = vim.o.guifont
 vim.go.guifont = vim.o.guifont
 vim.go.gfn = vim.go.guifont
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index 2c95ae8c92..d012b68556 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -7132,7 +7132,7 @@ function vim.fn.readblob(fname, offset, size) end
 --- Returns an empty List on error.
 ---
 --- @param directory string
---- @param expr? integer
+--- @param expr? integer|string|fun(name: string): integer
 --- @return any
 function vim.fn.readdir(directory, expr) end
 
@@ -7521,7 +7521,7 @@ function vim.fn.screenchars(row, col) end
 ---   noremap GG <Cmd>echom screencol()<CR>
 --- <
 ---
---- @return integer[]
+--- @return integer
 function vim.fn.screencol() end
 
 --- The result is a Dict with the screen position of the text
@@ -7550,7 +7550,7 @@ function vim.fn.screencol() end
 --- @param winid integer
 --- @param lnum integer
 --- @param col integer
---- @return any
+--- @return { col: integer, curscol: integer, endcol: integer, row: integer }
 function vim.fn.screenpos(winid, lnum, col) end
 
 --- The result is a Number, which is the current screen row of the
@@ -7969,7 +7969,7 @@ function vim.fn.searchpairpos(start, middle, end_, flags, skip, stopline, timeou
 --- @param stopline? integer
 --- @param timeout? integer
 --- @param skip? string|function
---- @return any
+--- @return { [1]: integer, [2]: integer, [3]: integer? }
 function vim.fn.searchpos(pattern, flags, stopline, timeout, skip) end
 
 --- Returns a list of server addresses, or empty if all servers
diff --git a/runtime/lua/vim/_meta/vvars.lua b/runtime/lua/vim/_meta/vvars.lua
index 58cdddce48..fde0af2f0e 100644
--- a/runtime/lua/vim/_meta/vvars.lua
+++ b/runtime/lua/vim/_meta/vvars.lua
@@ -6,24 +6,26 @@ error('Cannot require a meta file')
 --- @class vim.v
 vim.v = ...
 
---- The list of file arguments passed on the command line at startup.
----
---- Each filename is expanded to an absolute path, so that v:argf
---- remains valid even if the current working directory changes later.
+--- File arguments (expanded to absolute paths) given at startup.
 ---
 --- Unlike `v:argv`, this does not include option arguments
 --- such as `-u`, `--cmd`, or `+cmd`. Unlike `argv()`, it is not
 --- affected by later `:args`, `:argadd`, or plugin modifications.
---- It also handles the `--` separator correctly, including only
---- files specified after it.
 ---
---- This is a read-only snapshot of the original startup file arguments.
+--- Example:
+--- ```
+---   nvim file1.txt +ls -- file2.txt
+---   :echo v:argf
+---   " ['/path/to/cwd/file1.txt', '/path/to/cwd/file2.txt']
+--- ```
 --- @type string[]
 vim.v.argf = ...
 
---- The command line arguments Vim was invoked with.  This is a
---- list of strings.  The first item is the Vim command.
---- See `v:progpath` for the command with full path.
+--- Command line arguments (`-u`, `--cmd`, `+cmd`, …) Nvim was
+--- invoked with.  The first item is the Nvim command.
+---
+--- See `v:progpath` to get the full path to Nvim.
+--- See `v:argf` to get only file args, without other options.
 --- @type string[]
 vim.v.argv = ...
 
@@ -125,7 +127,9 @@ vim.v.ctype = ...
 vim.v.dying = ...
 
 --- Number of screen cells that can be used for an `:echo` message
---- in the last screen line before causing the `hit-enter-prompt`.
+--- in the last screen line before causing the `hit-enter` prompt
+--- (or "overflow" with `ui2`).
+---
 --- Depends on 'showcmd', 'ruler' and 'columns'.  You need to
 --- check 'cmdheight' for whether there are full-width lines
 --- available above the last line.
@@ -579,8 +583,6 @@ vim.v.relnum = ...
 --- screen to scroll up.  It's only set when it is empty, thus the
 --- first reason is remembered.  It is set to "Unknown" for a
 --- typed command.
---- This can be used to find out why your script causes the
---- hit-enter prompt.
 --- @type string
 vim.v.scrollstart = ...
 
diff --git a/runtime/lua/vim/_meta/vvars_extra.lua b/runtime/lua/vim/_meta/vvars_extra.lua
index 9fe0be4f27..41dcbce966 100644
--- a/runtime/lua/vim/_meta/vvars_extra.lua
+++ b/runtime/lua/vim/_meta/vvars_extra.lua
@@ -53,7 +53,7 @@ error('Cannot require a meta file')
 --- `v:event.operator` is "y".
 --- @field operator? string
 --- Text stored in the register as a |readfile()|-style list of lines.
---- @field regcontents? string
+--- @field regcontents? string|string[]
 --- Requested register (e.g "x" for "xyy) or the empty string for an unnamed operation.
 --- @field regname? string
 --- @field regtype? string Type of register as returned by |getregtype()|.
diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index 654ab9bf12..1bcfcaffa0 100644
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@@ -243,6 +243,7 @@ end
 --- -- { {id=1}, {id=2} }
 --- ```
 ---
+---@since 14
 ---@param key? fun(...):any Optional hash function to determine uniqueness of values.
 ---@return Iter
 ---@see |vim.list.unique()|
@@ -282,6 +283,7 @@ end
 --- -- error: attempt to flatten a dict-like table
 --- ```
 ---
+---@since 12
 ---@param depth? number Depth to which |list-iterator| should be flattened
 ---                        (defaults to 1)
 ---@return Iter
@@ -331,6 +333,7 @@ end
 --- -- { 6, 12 }
 --- ```
 ---
+---@since 12
 ---@param f fun(...):...:any Mapping function. Takes all values returned from
 ---                      the previous stage in the pipeline as arguments
 ---                      and returns one or more new values, which are used
@@ -399,6 +402,7 @@ end
 ---
 --- For functions with side effects. To modify the values in the iterator, use |Iter:map()|.
 ---
+---@since 12
 ---@param f fun(...) Function to execute for each item in the pipeline.
 ---                  Takes all of the values returned by the previous stage
 ---                  in the pipeline as arguments.
@@ -446,6 +450,7 @@ end
 --- To create a map-like table with arbitrary keys, use |Iter:fold()|.
 ---
 ---
+---@since 12
 ---@return table
 function Iter:totable()
   local t = {}
@@ -498,6 +503,7 @@ end
 ---
 --- Consumes the iterator.
 ---
+--- @since 12
 --- @param delim string Delimiter
 --- @return string
 function Iter:join(delim)
@@ -527,6 +533,7 @@ end
 ---
 ---@generic A
 ---
+---@since 12
 ---@param init A Initial value of the accumulator.
 ---@param f fun(acc:A, ...):A Accumulation function.
 ---@return A
@@ -572,6 +579,7 @@ end
 ---
 --- ```
 ---
+---@since 12
 ---@return any
 function Iter:next()
   if self._peeked then
@@ -606,6 +614,7 @@ end
 ---
 --- ```
 ---
+---@since 12
 ---@return Iter
 function Iter:rev()
   error('rev() requires an array-like table')
@@ -637,6 +646,7 @@ end
 ---
 --- ```
 ---
+---@since 12
 ---@return any
 function Iter:peek()
   if not self._peeked then
@@ -674,6 +684,7 @@ end
 --- -- 12
 ---
 --- ```
+---@since 12
 ---@param f any
 ---@return any
 function Iter:find(f)
@@ -720,6 +731,7 @@ end
 ---
 ---@see |Iter:find()|
 ---
+---@since 12
 ---@param f any
 ---@return any
 ---@diagnostic disable-next-line: unused-local
@@ -769,6 +781,7 @@ end
 --- -- nil
 --- ```
 ---
+---@since 12
 ---@param n integer|fun(...):boolean Number of values to take or a predicate.
 ---@return Iter
 function Iter:take(n)
@@ -828,6 +841,7 @@ end
 --- -- 3
 --- ```
 ---
+---@since 12
 ---@return any
 function Iter:pop()
   error('pop() requires an array-like table')
@@ -858,6 +872,7 @@ end
 ---
 ---@see |Iter:last()|
 ---
+---@since 12
 ---@return any
 function Iter:rpeek()
   error('rpeek() requires an array-like table')
@@ -891,6 +906,7 @@ end
 --- -- 12
 --- ```
 ---
+---@since 12
 ---@param n integer|fun(...):boolean Number of values to skip or a predicate.
 ---@return Iter
 function Iter:skip(n)
@@ -956,6 +972,7 @@ end
 --- -- 3
 --- ```
 ---
+---@since 12
 ---@param n number Number of values to skip.
 ---@return Iter
 ---@diagnostic disable-next-line: unused-local
@@ -993,6 +1010,7 @@ end
 --- -- 3
 --- ```
 ---
+---@since 12
 ---@param n number Index of the value to return. May be negative if the source is a |list-iterator|.
 ---@return any
 function Iter:nth(n)
@@ -1007,6 +1025,7 @@ end
 ---
 --- Equivalent to `:skip(first - 1):rskip(len - last + 1)`.
 ---
+---@since 12
 ---@param first number
 ---@param last number
 ---@return Iter
@@ -1022,6 +1041,7 @@ end
 
 --- Returns true if any of the items in the iterator match the given predicate.
 ---
+---@since 12
 ---@param pred fun(...):boolean Predicate function. Takes all values returned from the previous
 ---                          stage in the pipeline as arguments and returns true if the
 ---                          predicate matches.
@@ -1046,6 +1066,7 @@ end
 
 --- Returns true if all items in the iterator match the given predicate.
 ---
+---@since 12
 ---@param pred fun(...):boolean Predicate function. Takes all values returned from the previous
 ---                          stage in the pipeline as arguments and returns true if the
 ---                          predicate matches.
@@ -1083,6 +1104,7 @@ end
 ---
 --- ```
 ---
+---@since 12
 ---@see |Iter:rpeek()|
 ---
 ---@return any
@@ -1135,6 +1157,7 @@ end
 ---
 --- ```
 ---
+---@since 12
 ---@return Iter
 function Iter:enumerate()
   local i = 0
diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua
index d1ed9138ea..5aa473968f 100644
--- a/runtime/lua/vim/lsp.lua
+++ b/runtime/lua/vim/lsp.lua
@@ -1046,13 +1046,11 @@ end
 --- ```
 ---
 --- By default asks the server to shutdown, unless stop was requested already for this client (then
---- force-shutdown is attempted, unless `exit_timeout=false`).
+--- force-stop is attempted, unless `exit_timeout=false`).
 ---
 ---@deprecated
 ---@param client_id integer|integer[]|vim.lsp.Client[] id, list of id's, or list of |vim.lsp.Client| objects
----@param force? boolean|integer Whether to shutdown forcefully.
---- If `force` is a number, it will be treated as the time in milliseconds to
---- wait before forcing the shutdown.
+---@param force? boolean|integer See |Client:stop()|
 function lsp.stop_client(client_id, force)
   vim.deprecate('vim.lsp.stop_client()', 'vim.lsp.Client:stop()', '0.13')
   --- @type integer[]|vim.lsp.Client[]
diff --git a/runtime/lua/vim/lsp/client.lua b/runtime/lua/vim/lsp/client.lua
index d98f1c000f..635c2cde76 100644
--- a/runtime/lua/vim/lsp/client.lua
+++ b/runtime/lua/vim/lsp/client.lua
@@ -68,9 +68,11 @@ local all_clients = {}
 --- (default: `true`)
 --- @field detached? boolean
 ---
---- Milliseconds to wait for server to exit cleanly after sending the "shutdown" request before
---- sending kill -15. If set to false, waits indefinitely. If set to true, nvim will kill the
---- server immediately.
+--- Decides if/when to force-stop the server after sending the "shutdown" request. See |Client:stop()|.
+--- Note: when Nvim itself is exiting,
+--- - `false`: Nvim will not force-stop LSP server(s).
+--- - `true`: Nvim will force-stop LSP server(s) that did not comply with the "shutdown" request.
+--- - `number`: Nvim will wait up to `exit_timeout` milliseconds before performing force-stop.
 --- (default: `false`)
 --- @field exit_timeout? integer|boolean
 ---
@@ -156,9 +158,7 @@ local all_clients = {}
 --- Capabilities provided at runtime (after startup).
 --- @field dynamic_capabilities lsp.DynamicCapabilities
 ---
---- Milliseconds to wait for server to exit cleanly after sending the "shutdown" request before
---- sending kill -15. If set to false, waits indefinitely. If set to true, nvim will kill the
---- server immediately.
+--- See [vim.lsp.ClientConfig].
 --- (default: `false`)
 --- @field exit_timeout integer|boolean
 ---
@@ -852,20 +852,19 @@ end
 
 --- Stops a client, optionally with force after a timeout.
 ---
---- By default, it will request the server to shutdown, then force a shutdown
---- if the server has not exited after `self.exit_timeout` milliseconds. If
---- you request to stop a client which has previously been requested to
---- shutdown, it will automatically escalate and force shutdown immediately,
---- regardless of the value of `force` (or `self.exit_timeout` if `nil`).
+--- By default this sends a "shutdown" request to the server, escalating to force-stop if the server
+--- has not exited after `self.exit_timeout` milliseconds (unless `exit_timeout=false`).
+--- Calling stop() on a client that was previously requested to shutdown, will escalate to
+--- force-stop immediately, regardless of `force` (or `self.exit_timeout` if `force=nil`).
 ---
---- Note: Forcing shutdown while a server is busy writing out project or index
---- files can lead to file corruption.
+--- Note: Forcing shutdown while a server is busy writing out project or index files can lead to
+--- file corruption.
 ---
---- @param force? integer|boolean Time in milliseconds to wait before forcing
----                               a shutdown. If false, only request the
----                               server to shutdown, but don't force it. If
----                               true, force a shutdown immediately.
----                               (default: `self.exit_timeout`)
+--- @param force? integer|boolean (default: `self.exit_timeout`) Decides whether to force-stop the server.
+--- - `nil`: Defaults to `exit_timeout` from |vim.lsp.ClientConfig|.
+--- - `true`: Force-stop after "shutdown" request.
+--- - `false`: Do not force-stop after "shutdown" request.
+--- - number: Wait up to `force` milliseconds before force-stop.
 function Client:stop(force)
   validate('force', force, { 'number', 'boolean' }, true)
 
diff --git a/runtime/lua/vim/lsp/completion.lua b/runtime/lua/vim/lsp/completion.lua
index 4910c415d9..e495af4240 100644
--- a/runtime/lua/vim/lsp/completion.lua
+++ b/runtime/lua/vim/lsp/completion.lua
@@ -6,7 +6,7 @@
 ---
 --- Example: activate LSP-driven auto-completion:
 --- ```lua
---- -- Works best with completeopt=noselect.
+--- -- Works best if 'completeopt' has "noselect".
 --- -- Use CTRL-Y to select an item. |complete_CTRL-Y|
 --- vim.cmd[[set completeopt+=menuone,noselect,popup]]
 --- vim.lsp.start({
@@ -1159,15 +1159,14 @@ end
 --- Enables or disables completions from the given language client in the given
 --- buffer. Effects of enabling completions are:
 ---
---- - Calling |vim.lsp.completion.get()| uses the enabled clients to retrieve
----   completion candidates
+--- - Calling |vim.lsp.completion.get()| uses the enabled clients to retrieve completion candidates.
+--- - Selecting a completion item shows a preview popup ("completionItem/resolve") if 'completeopt'
+---   has "popup".
+--- - Accepting a completion item using `<c-y>` applies side effects like expanding snippets,
+---   text edits (e.g. insert import statements) and executing associated commands. This works for
+---   completions triggered via autotrigger, 'omnifunc' or [vim.lsp.completion.get()].
 ---
---- - Accepting a completion candidate using `<c-y>` applies side effects like
----   expanding snippets, text edits (e.g. insert import statements) and
----   executing associated commands. This works for completions triggered via
----   autotrigger, omnifunc or completion.get()
----
---- Example: |lsp-attach| |lsp-completion|
+--- Examples: |lsp-attach| |lsp-completion|
 ---
 --- Note: the behavior of `autotrigger=true` is controlled by the LSP `triggerCharacters` field. You
 --- can override it on LspAttach, see |lsp-autocompletion|.
diff --git a/runtime/lua/vim/pack.lua b/runtime/lua/vim/pack.lua
index c59a9b410a..6d9b8dc9a1 100644
--- a/runtime/lua/vim/pack.lua
+++ b/runtime/lua/vim/pack.lua
@@ -1204,9 +1204,8 @@ end
 --- @field offline? boolean Whether to skip downloading new updates. Default: `false`.
 ---
 --- How to compute a new plugin revision. One of:
----     - "version" (default) - use latest revision matching `version` from plugin specification.
----     - "lockfile" - use revision from the lockfile. Useful for reverting or performing controlled
----       update.
+---   - "version" (default): use latest revision matching `version` from plugin specification.
+---   - "lockfile": use revision from the lockfile. For reverting or performing controlled update.
 --- @field target? string
 
 --- Update plugins
diff --git a/runtime/lua/vim/pack/_lsp.lua b/runtime/lua/vim/pack/_lsp.lua
index f0d3dc235b..f40d65ddea 100644
--- a/runtime/lua/vim/pack/_lsp.lua
+++ b/runtime/lua/vim/pack/_lsp.lua
@@ -167,7 +167,7 @@ local commands = {
   end,
 }
 
--- NOTE: Use `vim.schedule_wrap` to avoid press-enter after choosing code
+-- NOTE: Use `vim.schedule_wrap` to avoid hit-enter after choosing code
 -- action via built-in `vim.fn.inputlist()`
 --- @param params { command: string, arguments: table }
 --- @param callback function
diff --git a/runtime/lua/vim/secure.lua b/runtime/lua/vim/secure.lua
index 784b4d5ff0..9f5463ac98 100644
--- a/runtime/lua/vim/secure.lua
+++ b/runtime/lua/vim/secure.lua
@@ -162,9 +162,10 @@ end
 --- @class vim.trust.opts
 --- @inlinedoc
 ---
---- - `'allow'` to add a file to the trust database and trust it,
---- - `'deny'` to add a file to the trust database and deny it,
---- - `'remove'` to remove file from the trust database
+--- One of:
+---   - `'allow'` to add a file to the trust database and trust it,
+---   - `'deny'` to add a file to the trust database and deny it,
+---   - `'remove'` to remove file from the trust database
 --- @field action 'allow'|'deny'|'remove'
 ---
 --- Path to a file to update. Mutually exclusive with {bufnr}.
diff --git a/runtime/lua/vim/treesitter/query.lua b/runtime/lua/vim/treesitter/query.lua
index 7fa954698d..d29e376ef1 100644
--- a/runtime/lua/vim/treesitter/query.lua
+++ b/runtime/lua/vim/treesitter/query.lua
@@ -1193,10 +1193,8 @@ end
 --- parsers.
 ---
 --- If you move the cursor to a capture name ("@foo"), text matching the capture is highlighted
---- with |hl-DiagnosticVirtualTextHint| in the source buffer.
----
---- The query editor is a scratch buffer, use `:write` to save it. You can find example queries
---- at `$VIMRUNTIME/queries/`.
+--- with |hl-DiagnosticVirtualTextHint| in the source buffer. The query editor is a scratch buffer,
+--- use `:write` to save it. You can find example queries at `$VIMRUNTIME/queries/`.
 ---
 --- @param lang? string language to open the query editor for. If omitted, inferred from the current buffer's filetype.
 function M.edit(lang)