docs: lsp config/commands #33122

fix #33075

2 files changed, 100 insertions, 72 deletions

diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index 5e684ab408..62df0a7707 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -1796,41 +1796,40 @@ function vim.api.nvim_open_term(buffer, opts) end
 ---                   region is hidden by setting `eob` flag of
 ---                  'fillchars' to a space char, and clearing the
 ---                  `hl-EndOfBuffer` region in 'winhighlight'.
---- - border: Style of (optional) window border. This can either be a string
----   or an array. The string values are the same as those described in 'winborder'.
----   If it is an array, it should have a length of eight or any divisor of
----   eight. The array will specify the eight chars building up the border
----   in a clockwise fashion starting with the top-left corner. As an
----   example, the double box style could be specified as:
----     ```
----     [ "╔", "═" ,"╗", "║", "╝", "═", "╚", "║" ].
----     ```
----     If the number of chars are less than eight, they will be repeated. Thus
----     an ASCII border could be specified as
----     ```
----     [ "/", "-", \"\\\\\", "|" ],
----     ```
----     or all chars the same as
----     ```
----     [ "x" ].
----     ```
----   An empty string can be used to turn off a specific border, for instance,
+--- - border: (`string|string[]`) (defaults to 'winborder' option) Window border. The string form
+---   accepts the same values as the 'winborder' option. The array form must have a length of
+---   eight or any divisor of eight, specifying the chars that form the border in a clockwise
+---   fashion starting from the top-left corner. For example, the double-box style can be
+---   specified as:
 ---   ```
----     [ "", "", "", ">", "", "", "", "<" ]
+---   [ "╔", "═" ,"╗", "║", "╝", "═", "╚", "║" ].
 ---   ```
----   will only make vertical borders but not horizontal ones.
----   By default, `FloatBorder` highlight is used, which links to `WinSeparator`
----   when not defined.  It could also be specified by character:
+---   If fewer than eight chars are given, they will be repeated. An ASCII border could be
+---   specified as:
 ---   ```
----     [ ["+", "MyCorner"], ["x", "MyBorder"] ].
+---   [ "/", "-", \"\\\\\", "|" ],
 ---   ```
---- - title: Title (optional) in window border, string or list.
+---   Or one char for all sides:
+---   ```
+---   [ "x" ].
+---   ```
+---   Empty string can be used to hide a specific border. This example will show only vertical
+---   borders, not horizontal:
+---   ```
+---   [ "", "", "", ">", "", "", "", "<" ]
+---   ```
+---   By default, `hl-FloatBorder` highlight is used, which links to `hl-WinSeparator` when not
+---   defined.  Each border side can specify an optional highlight:
+---   ```
+---   [ ["+", "MyCorner"], ["x", "MyBorder"] ].
+---   ```
+--- - title: (optional) Title in window border, string or list.
 ---   List should consist of `[text, highlight]` tuples.
 ---   If string, or a tuple lacks a highlight, the default highlight group is `FloatTitle`.
 --- - title_pos: Title position. Must be set with `title` option.
 ---   Value can be one of "left", "center", or "right".
 ---   Default is `"left"`.
---- - footer: Footer (optional) in window border, string or list.
+--- - footer: (optional) Footer in window border, string or list.
 ---   List should consist of `[text, highlight]` tuples.
 ---   If string, or a tuple lacks a highlight, the default highlight group is `FloatFooter`.
 --- - footer_pos: Footer position. Must be set with `footer` option.
diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua
index 3dcf692d24..995340d751 100644
--- a/runtime/lua/vim/lsp.lua
+++ b/runtime/lua/vim/lsp.lua
@@ -296,49 +296,64 @@ end
 --- root_dir matches.
 --- @field reuse_client? fun(client: vim.lsp.Client, config: vim.lsp.ClientConfig): boolean
 
---- Update the configuration for an LSP client.
+--- Sets the default configuration for an LSP client (or _all_ clients if the special name "*" is
+--- used).
 ---
---- Use name '*' to set default configuration for all clients.
----
---- Can also be table-assigned to redefine the configuration for a client.
+--- Can also be accessed by table-indexing (`vim.lsp.config[…]`) to get the resolved config, or
+--- redefine the config (instead of "merging" with the config chain).
 ---
 --- Examples:
 ---
---- - Add a root marker for all clients:
+--- - Add root markers for ALL clients:
+---   ```lua
+---   vim.lsp.config('*', {
+---       root_markers = { '.git', '.hg' },
+---     })
+---   ```
+--- - Add capabilities to ALL clients:
 ---   ```lua
----      vim.lsp.config('*', {
----          root_markers = { '.git' },
----        })
----        ```
---- - Add additional capabilities to all clients:
+---   vim.lsp.config('*', {
+---     capabilities = {
+---       textDocument = {
+---         semanticTokens = {
+---           multilineTokenSupport = true,
+---         }
+---       }
+---     }
+---   })
+---   ```
+--- - Add root markers and capabilities for "clangd":
 ---   ```lua
----      vim.lsp.config('*', {
----          capabilities = {
----            textDocument = {
----              semanticTokens = {
----                multilineTokenSupport = true,
----              }
----            }
----          }
----        })
----        ```
---- - (Re-)define the configuration for clangd:
+---   vim.lsp.config('clangd', {
+---     root_markers = { '.clang-format', 'compile_commands.json' },
+---     capabilities = {
+---       textDocument = {
+---         completion = {
+---           completionItem = {
+---             snippetSupport = true,
+---           }
+---         }
+---       }
+---     }
+---   })
+---   ```
+--- - (Re-)define the "clangd" configuration (overrides the resolved chain):
 ---   ```lua
----      vim.lsp.config.clangd = {
----          cmd = {
----            'clangd',
----            '--clang-tidy',
----            '--background-index',
----            '--offset-encoding=utf-8',
----          },
----          root_markers = { '.clangd', 'compile_commands.json' },
----          filetypes = { 'c', 'cpp' },
----        }
----        ```
---- - Get configuration for luals:
+---   vim.lsp.config.clangd = {
+---     cmd = {
+---       'clangd',
+---       '--clang-tidy',
+---       '--background-index',
+---       '--offset-encoding=utf-8',
+---     },
+---     root_markers = { '.clangd', 'compile_commands.json' },
+---     filetypes = { 'c', 'cpp' },
+---   }
+---   ```
+--- - Get the resolved configuration for "luals":
 ---   ```lua
----      local cfg = vim.lsp.config.luals
----        ```
+---   local cfg = vim.lsp.config.luals
+---   ```
 ---
 --- @param name string
 --- @param cfg vim.lsp.Config
@@ -1524,25 +1539,39 @@ function lsp.with(handler, override_config)
   end
 end
 
---- Registry for client side commands.
---- This is an extension point for plugins to handle custom commands which are
---- not part of the core language server protocol specification.
+--- Registry (a table) for client-side handlers, for custom server-commands that are not in the LSP
+--- specification.
 ---
---- The registry is a table where the key is a unique command name,
---- and the value is a function which is called if any LSP action
---- (code action, code lenses, ...) triggers the command.
+--- If an LSP response contains a command which is not found in `vim.lsp.commands`, the command will
+--- be executed via the LSP server using `workspace/executeCommand`.
 ---
---- If an LSP response contains a command for which no matching entry is
---- available in this registry, the command will be executed via the LSP server
---- using `workspace/executeCommand`.
+--- Each key in the table is a unique command name, and each value is a function which is called
+--- when an LSP action (code action, code lenses, …) triggers the command.
 ---
---- The first argument to the function will be the `Command`:
+--- - Argument 1 is the `Command`:
+---   ```
 ---   Command
 ---     title: String
 ---     command: String
 ---     arguments?: any[]
+---   ```
+--- - Argument 2 is the |lsp-handler| `ctx`.
+---
+--- Example:
+---
+--- ```lua
+--- vim.lsp.commands['java.action.generateToStringPrompt'] = function(_, ctx)
+---   require("jdtls.async").run(function()
+---     local _, result = request(ctx.bufnr, 'java/checkToStringStatus', ctx.params)
+---     local fields = ui.pick_many(result.fields, 'Include item in toString?', function(x)
+---       return string.format('%s: %s', x.name, x.type)
+---     end)
+---     local _, edit = request(ctx.bufnr, 'java/generateToString', { context = ctx.params; fields = fields; })
+---     vim.lsp.util.apply_workspace_edit(edit, offset_encoding)
+---   end)
+--- end
+--- ```
 ---
---- The second argument is the `ctx` of |lsp-handler|
 --- @type table<string,function>
 lsp.commands = setmetatable({}, {
   __newindex = function(tbl, key, value)