docs: vim.fs., diagnostics, lsp #34488

backport of #34402

(cherry picked from commit 8001276bd0)

runtime/lua/vim/_editor.lua

@@ -399,22 +399,23 @@ local VIM_CMD_ARG_MAX = 20
 
 --- Executes Vimscript (|Ex-commands|).
 ---
---- Note that `vim.cmd` can be indexed with a command name to return a callable function to the
---- command.
+--- Can be indexed with a command name to get a function, thus you can write `vim.cmd.echo(…)`
+--- instead of `vim.cmd{cmd='echo',…}`.
 ---
---- Example:
+--- Examples:
 ---
 --- ```lua
+--- -- Single command:
 --- vim.cmd('echo 42')
+--- -- Multiline script:
 --- vim.cmd([[
----   augroup My_group
+---   augroup my.group
 ---     autocmd!
 ---     autocmd FileType c setlocal cindent
 ---   augroup END
 --- ]])
 ---
---- -- Ex command :echo "foo"
---- -- Note string literals need to be double quoted.
+--- -- Ex command :echo "foo". Note: string literals must be double-quoted.
 --- vim.cmd('echo "foo"')
 --- vim.cmd { cmd = 'echo', args = { '"foo"' } }
 --- vim.cmd.echo({ args = { '"foo"' } })
@@ -422,22 +423,19 @@ local VIM_CMD_ARG_MAX = 20
 ---
 --- -- Ex command :write! myfile.txt
 --- vim.cmd('write! myfile.txt')
---- vim.cmd { cmd = 'write', args = { "myfile.txt" }, bang = true }
---- vim.cmd.write { args = { "myfile.txt" }, bang = true }
---- vim.cmd.write { "myfile.txt", bang = true }
+--- vim.cmd { cmd = 'write', args = { 'myfile.txt' }, bang = true }
+--- vim.cmd.write { args = { 'myfile.txt' }, bang = true }
+--- vim.cmd.write { 'myfile.txt', bang = true }
 ---
---- -- Ex command :colorscheme blue
---- vim.cmd('colorscheme blue')
---- vim.cmd.colorscheme('blue')
+--- -- Ex command :vertical resize +2
+--- vim.cmd.resize({ '+2', mods = { vertical = true } })
 --- ```
 ---
 ---@diagnostic disable-next-line: undefined-doc-param
 ---@param command string|table Command(s) to execute.
----                            If a string, executes multiple lines of Vimscript at once. In this
----                            case, it is an alias to |nvim_exec2()|, where `opts.output` is set
----                            to false. Thus it works identical to |:source|.
----                            If a table, executes a single command. In this case, it is an alias
----                            to |nvim_cmd()| where `opts` is empty.
+---       - The string form supports multiline Vimscript (alias to |nvim_exec2()|, behaves
+---         like |:source|).
+---       - The table form executes a single command (alias to |nvim_cmd()|).
 ---@see |ex-cmd-index|
 vim.cmd = setmetatable({}, {
   __call = function(_, command)

runtime/lua/vim/fs.lua

@@ -375,7 +375,7 @@ end
 --- If the buffer is unnamed (has no backing file) or has a non-empty 'buftype' then the search
 --- begins from Nvim's |current-directory|.
 ---
---- Example:
+--- Examples:
 ---
 --- ```lua
 --- -- Find the root of a Python project, starting from file 'main.py'
@@ -397,20 +397,12 @@ end
 --- @since 12
 --- @param source integer|string Buffer number (0 for current buffer) or file path (absolute or
 ---               relative to the |current-directory|) to begin the search from.
---- @param marker (string|string[]|fun(name: string, path: string): boolean)[]|string|fun(name: string, path: string): boolean A marker or a list of markers.
----               A marker has one of three types: string, a list of strings or a function. The
----               parameter also accepts a list of markers, each of which is any of those three
----               types. If a marker is a function, it is called for each evaluated item and
----               should return true if {name} and {path} are a match. If a list of markers is
----               passed, each marker in the list is evaluated in order and the first marker
----               which is matched returns the parent directory that it found. This allows
----               listing markers with priority. E.g. - in the following list, a parent directory
----               containing either 'a' or 'b' is searched for. If neither is found, then 'c' is
----               searched for. So, 'c' has lower priority than 'a' and 'b' which have equal
----               priority.
----               ```lua
----                   marker = { { 'a', 'b' }, 'c' }
----               ```
+--- @param marker (string|string[]|fun(name: string, path: string): boolean)[]|string|fun(name: string, path: string): boolean
+---               Filename, function, or list thereof, that decides how to find the root. To
+---               indicate "equal priority", specify items in a nested list `{ { 'a.txt', 'b.lua' }, … }`.
+---               A function item must return true if `name` and `path` are a match. Each item
+---               (which may itself be a nested list) is evaluated in-order against all ancestors,
+---               until a match is found.
 --- @return string? # Directory path containing one of the given markers, or nil if no directory was
 ---                   found.
 function M.root(source, marker)

runtime/lua/vim/lsp.lua

@@ -275,6 +275,7 @@ end
 --- @class vim.lsp.Config : vim.lsp.ClientConfig
 ---
 --- See `cmd` in [vim.lsp.ClientConfig].
+--- See also `reuse_client` to dynamically decide (per-buffer) when `cmd` should be re-invoked.
 --- @field cmd? string[]|fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient
 ---
 --- Filetypes the client will attach to, if activated by `vim.lsp.enable()`. If not provided, the

runtime/lua/vim/lsp/client.lua

@@ -43,13 +43,12 @@ local validate = vim.validate
 ---   array.
 --- @field capabilities? lsp.ClientCapabilities
 ---
---- command string[] that launches the language
---- server (treated as in |jobstart()|, must be absolute or on `$PATH`, shell constructs like
---- "~" are not expanded), or function that creates an RPC client. Function receives
---- a `dispatchers` table and returns a table with member functions `request`, `notify`,
---- `is_closing` and `terminate`.
+--- Command `string[]` that launches the language server (treated as in |jobstart()|, must be
+--- absolute or on `$PATH`, shell constructs like "~" are not expanded), or function that creates an
+--- RPC client. Function receives a `dispatchers` table and returns a table with member functions
+--- `request`, `notify`, `is_closing` and `terminate`.
 --- See |vim.lsp.rpc.request()|, |vim.lsp.rpc.notify()|.
----  For TCP there is a builtin RPC client factory: |vim.lsp.rpc.connect()|
+--- For TCP there is a builtin RPC client factory: |vim.lsp.rpc.connect()|
 --- @field cmd string[]|fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient
 ---
 --- Directory to launch the `cmd` process. Not related to `root_dir`.