docs: news, intro, lsp, api #33687

runtime/lua/vim/lsp.lua

@@ -286,43 +286,35 @@ end
 --- implementation re-uses a client if name and root_dir matches.
 --- @field reuse_client? fun(client: vim.lsp.Client, config: vim.lsp.ClientConfig): boolean
 ---
---- [lsp-root_dir()]() Directory where the LSP server will base its workspaceFolders, rootUri, and
---- rootPath on initialization. The function form receives a buffer number and `on_dir` callback
---- which it must call to provide root_dir, or LSP will not be activated for the buffer. Thus
---- a `root_dir()` function can dynamically decide per-buffer whether to activate (or skip) LSP. See
---- example at |vim.lsp.enable()|.
+--- [lsp-root_dir()]()
+--- Decides the workspace root: the directory where the LSP server will base its workspaceFolders,
+--- rootUri, and rootPath on initialization. The function form must call the `on_dir` callback to
+--- provide the root dir, or LSP will not be activated for the buffer. Thus a `root_dir()` function
+--- can dynamically decide per-buffer whether to activate (or skip) LSP.
+--- See example at |vim.lsp.enable()|.
 --- @field root_dir? string|fun(bufnr: integer, on_dir:fun(root_dir?:string))
 ---
---- Directory markers (.e.g. '.git/') where the LSP server will base its workspaceFolders,
---- rootUri, and rootPath on initialization. Unused if `root_dir` is provided.
+--- [lsp-root_markers]()
+--- Filename(s) (".git/", "package.json", …) used to decide the workspace root. Unused if `root_dir`
+--- is defined. The list order decides priority. To indicate "equal priority", specify names in
+--- a nested list `{ { 'a.txt', 'b.lua' }, ... }`.
 ---
---- The list order decides the priority. To indicate "equal priority", specify names in a nested list (`{ { 'a', 'b' }, ... }`)
---- Each entry in this list is a set of one or more markers. For each set, Nvim
---- will search upwards for each marker contained in the set. If a marker is
---- found, the directory which contains that marker is used as the root
---- directory. If no markers from the set are found, the process is repeated
---- with the next set in the list.
----
---- Example:
+--- For each item, Nvim will search upwards (from the buffer file) for that marker, or list of
+--- markers; search stops at the first directory containing that marker, and the directory is used
+--- as the root dir (workspace folder).
 ---
+--- Example: Find the first ancestor directory containing file or directory "stylua.toml"; if not
+--- found, find the first ancestor containing ".git":
 --- ```lua
 ---   root_markers = { 'stylua.toml', '.git' }
 --- ```
 ---
---- Find the first parent directory containing the file `stylua.toml`. If not
---- found, find the first parent directory containing the file or directory
---- `.git`.
----
---- Example:
----
+--- Example: Find the first ancestor directory containing EITHER "stylua.toml" or ".luarc.json"; if
+--- not found, find the first ancestor containing ".git":
 --- ```lua
 ---   root_markers = { { 'stylua.toml', '.luarc.json' }, '.git' }
 --- ```
 ---
---- Find the first parent directory containing EITHER `stylua.toml` or
---- `.luarc.json`. If not found, find the first parent directory containing the
---- file or directory `.git`.
----
 --- @field root_markers? (string|string[])[]
 
 --- Sets the default configuration for an LSP client (or _all_ clients if the special name "*" is
@@ -587,6 +579,14 @@ end
 --- vim.lsp.enable({'luals', 'pyright'})
 --- ```
 ---
+--- Example: [lsp-restart]() Passing `false` stops and detaches the client(s). Thus you can
+--- "restart" LSP by disabling and re-enabling a given config:
+---
+--- ```lua
+--- vim.lsp.enable('clangd', false)
+--- vim.lsp.enable('clangd', true)
+--- ```
+---
 --- Example: To _dynamically_ decide whether LSP is activated, define a |lsp-root_dir()| function
 --- which calls `on_dir()` only when you want that config to activate:
 ---
@@ -603,7 +603,8 @@ end
 ---@since 13
 ---
 --- @param name string|string[] Name(s) of client(s) to enable.
---- @param enable? boolean `true|nil` to enable, `false` to disable.
+--- @param enable? boolean `true|nil` to enable, `false` to disable (actively stops and detaches
+--- clients as needed)
 function lsp.enable(name, enable)
   validate('name', name, { 'string', 'table' })
 
@@ -648,6 +649,8 @@ end
 
 --- Checks if the given LSP config is enabled (globally, not per-buffer).
 ---
+--- Unlike `vim.lsp.config['…']`, this does not have the side-effect of resolving the config.
+---
 --- @param name string Config name
 --- @return boolean
 function lsp.is_enabled(name)