docs: api, messages, lsp, trust

gen_vimdoc.lua: In prepare for the upcoming release, comment-out the
"Experimental" warning for prerelease features.

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)
 

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|.