commit 644c6188254b79c8a200ba474cf3b9b478185e16
parent 52a4bc45488cb1f626b02be5512cd0301cd48cb8
Author: Justin M. Keyes <justinkz@gmail.com>
Date: Sun, 27 Apr 2025 15:44:11 -0700
docs: lsp, lua #33682
- sort fields alphabetically.
- in the `vim.lsp.Client` docs, reference `vim.lsp.ClientConfig` instead
of duplicating its docs.
- cleanup lots of redundant-yet-drifted field docs.
Diffstat:
9 files changed, 261 insertions(+), 287 deletions(-)
diff --git a/runtime/doc/dev_vimpatch.txt b/runtime/doc/dev_vimpatch.txt
@@ -311,7 +311,7 @@ Nvim's filetype detection behavior matches Vim, but is implemented as part of
|vim.filetype| (see `$VIMRUNTIME/lua/vim/filetype.lua`). The logic is encoded in
three tables, listed in order of precedence (the first match is returned):
1. `filename` for literal full path or basename lookup;
-2. `pattern` for matching filenames or paths against |lua-patterns|, optimized
+2. `pattern` for matching filenames or paths against |lua-pattern|s, optimized
for fast lookup;
3. `extension` for literal extension lookup.
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
@@ -706,27 +706,25 @@ Lua module: vim.lsp *lsp-core*
• {cmd}? (`string[]|fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient`)
See `cmd` in |vim.lsp.ClientConfig|.
• {filetypes}? (`string[]`) Filetypes the client will attach to, if
- activated by `vim.lsp.enable()`. If not provided,
- then the client will attach to all filetypes.
- • {root_markers}? (`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.
- • {root_dir}? (`string|fun(bufnr: integer, on_dir:fun(root_dir?:string))`)
- *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 must be called to
- provide root_dir as a string. LSP will not be
- activated for the buffer unless `on_dir` is called;
- thus a `root_dir()` function can dynamically decide
- whether to activate (or skip) LSP per-buffer. See
- example at |vim.lsp.enable()|.
+ activated by `vim.lsp.enable()`. If not provided, the
+ client will attach to all filetypes.
• {reuse_client}? (`fun(client: vim.lsp.Client, config: vim.lsp.ClientConfig): boolean`)
- Predicate used to decide if a client should be
+ Predicate which decides if a client should be
re-used. Used on all running clients. The default
implementation re-uses a client if name and root_dir
matches.
+ • {root_dir}? (`string|fun(bufnr: integer, on_dir:fun(root_dir?:string))`)
+ *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()|.
+ • {root_markers}? (`string[]`) Directory markers (e.g. ".git/",
+ "package.json") used to decide `root_dir`. Unused if
+ `root_dir` is provided.
buf_attach_client({bufnr}, {client_id}) *vim.lsp.buf_attach_client()*
@@ -1196,65 +1194,17 @@ Lua module: vim.lsp.client *lsp-client*
*vim.lsp.Client*
Fields: ~
- • {id} (`integer`) The id allocated to the client.
- • {name} (`string`) If a name is specified on creation,
- that will be used. Otherwise it is just the
- client id. This is used for logs and messages.
- • {rpc} (`vim.lsp.rpc.PublicClient`) RPC client
- object, for low level interaction with the
- client. See |vim.lsp.rpc.start()|.
- • {offset_encoding} (`string`) Called "position encoding" in LSP
- spec, the encoding used for communicating with
- the server. You can modify this in the
- `config`'s `on_init` method before text is
- sent to the server.
- • {handlers} (`table<string,lsp.Handler>`) The handlers
- used by the client as described in
- |lsp-handler|.
- • {requests} (`table<integer,{ type: string, bufnr: integer, method: string}?>`)
- The current pending requests in flight to the
- server. Entries are key-value pairs with the
- key being the request id while the value is a
- table with `type`, `bufnr`, and `method`
- key-value pairs. `type` is either "pending"
- for an active request, or "cancel" for a
- cancel request. It will be "complete"
- ephemerally while executing |LspRequest|
- autocmds when replies are received from the
- server.
- • {config} (`vim.lsp.ClientConfig`) copy of the table
- that was passed by the user to
- |vim.lsp.start()|. See |vim.lsp.ClientConfig|.
- • {server_capabilities} (`lsp.ServerCapabilities?`) Response from the
- server sent on `initialize` describing the
- server's capabilities.
- • {server_info} (`lsp.ServerInfo?`) Response from the server
- sent on `initialize` describing information
- about the server.
- • {progress} (`vim.lsp.Client.Progress`) A ring buffer
- (|vim.ringbuf()|) containing progress messages
- sent by the server. See
- |vim.lsp.Client.Progress|.
- • {initialized} (`true?`)
- • {workspace_folders} (`lsp.WorkspaceFolder[]?`) The workspace
- folders configured in the client when the
- server starts. This property is only available
- if the client supports workspace folders. It
- can be `null` if the client supports workspace
- folders but none are configured.
- • {root_dir} (`string?`)
• {attached_buffers} (`table<integer,true>`)
+ • {capabilities} (`lsp.ClientCapabilities`) Capabilities
+ provided by the client (editor or tool), at
+ startup.
• {commands} (`table<string,fun(command: lsp.Command, ctx: table)>`)
- Table of command name to function which is
- called if any LSP action (code action, code
- lenses, ...) triggers the command. Client
- commands take precedence over the global
- command registry.
- • {settings} (`lsp.LSPObject`) Map with language server
- specific settings. These are returned to the
- language server if requested via
- `workspace/configuration`. Keys are
- case-sensitive.
+ Client commands. See |vim.lsp.ClientConfig|.
+ • {config} (`vim.lsp.ClientConfig`) Copy of the config
+ passed to |vim.lsp.start()|. See
+ |vim.lsp.ClientConfig|.
+ • {dynamic_capabilities} (`lsp.DynamicCapabilities`) Capabilities
+ provided at runtime (after startup).
• {flags} (`table`) A table with flags for the client.
The current (experimental) flags are:
• {allow_incremental_sync}? (`boolean`,
@@ -1271,9 +1221,41 @@ Lua module: vim.lsp.client *lsp-client*
false, nvim exits immediately after sending
the "shutdown" request to the server.
• {get_language_id} (`fun(bufnr: integer, filetype: string): string`)
- • {capabilities} (`lsp.ClientCapabilities`) The capabilities
- provided by the client (editor or tool)
- • {dynamic_capabilities} (`lsp.DynamicCapabilities`)
+ See |vim.lsp.ClientConfig|.
+ • {handlers} (`table<string,lsp.Handler>`) See
+ |vim.lsp.ClientConfig|.
+ • {id} (`integer`) The id allocated to the client.
+ • {initialized} (`true?`)
+ • {name} (`string`) See |vim.lsp.ClientConfig|.
+ • {offset_encoding} (`string`) See |vim.lsp.ClientConfig|.
+ • {progress} (`vim.lsp.Client.Progress`) A ring buffer
+ (|vim.ringbuf()|) containing progress messages
+ sent by the server. See
+ |vim.lsp.Client.Progress|.
+ • {requests} (`table<integer,{ type: string, bufnr: integer, method: string}?>`)
+ The current pending requests in flight to the
+ server. Entries are key-value pairs with the
+ key being the request id while the value is a
+ table with `type`, `bufnr`, and `method`
+ key-value pairs. `type` is either "pending"
+ for an active request, or "cancel" for a
+ cancel request. It will be "complete"
+ ephemerally while executing |LspRequest|
+ autocmds when replies are received from the
+ server.
+ • {root_dir} (`string?`) See |vim.lsp.ClientConfig|.
+ • {rpc} (`vim.lsp.rpc.PublicClient`) RPC client
+ object, for low level interaction with the
+ client. See |vim.lsp.rpc.start()|.
+ • {server_capabilities} (`lsp.ServerCapabilities?`) Response from the
+ server sent on `initialize` describing the
+ server's capabilities.
+ • {server_info} (`lsp.ServerInfo?`) Response from the server
+ sent on `initialize` describing server
+ information (e.g. version).
+ • {settings} (`lsp.LSPObject`) See |vim.lsp.ClientConfig|.
+ • {workspace_folders} (`lsp.WorkspaceFolder[]?`) See
+ |vim.lsp.ClientConfig|.
• {request} (`fun(self: vim.lsp.Client, method: string, params: table?, handler: lsp.Handler?, bufnr: integer?): boolean, integer?`)
See |Client:request()|.
• {request_sync} (`fun(self: vim.lsp.Client, method: string, params: table, timeout_ms: integer?, bufnr: integer?): {err: lsp.ResponseError?, result:any}?, string?`)
@@ -1303,6 +1285,23 @@ Lua module: vim.lsp.client *lsp-client*
*vim.lsp.ClientConfig*
Fields: ~
+ • {before_init}? (`fun(params: lsp.InitializeParams, config: vim.lsp.ClientConfig)`)
+ Callback invoked before the LSP "initialize"
+ phase, where `params` contains the parameters
+ being sent to the server and `config` is the
+ config that was passed to |vim.lsp.start()|.
+ You can use this to modify parameters before
+ they are sent.
+ • {capabilities}? (`lsp.ClientCapabilities`) Map overriding the
+ default capabilities defined by
+ |vim.lsp.protocol.make_client_capabilities()|,
+ passed to the language server on
+ initialization. Hint: use
+ make_client_capabilities() and modify its
+ result.
+ • Note: To send an empty dictionary use
+ |vim.empty_dict()|, else it will be encoded
+ as an array.
• {cmd} (`string[]|fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient`)
command string[] that launches the language
server (treated as in |jobstart()|, must be
@@ -1318,65 +1317,58 @@ Lua module: vim.lsp.client *lsp-client*
|vim.lsp.rpc.connect()|
• {cmd_cwd}? (`string`, default: cwd) Directory to launch
the `cmd` process. Not related to `root_dir`.
- • {cmd_env}? (`table`) Environment flags to pass to the LSP
- on spawn. Must be specified using a table.
- Non-string values are coerced to string.
- Example: >lua
- { PORT = 8080; HOST = "0.0.0.0"; }
+ • {cmd_env}? (`table`) Environment variables passed to the
+ LSP process on spawn. Non-string values are
+ coerced to string. Example: >lua
+ { PORT = 8080; HOST = '0.0.0.0'; }
<
- • {detached}? (`boolean`, default: true) Daemonize the server
- process so that it runs in a separate process
- group from Nvim. Nvim will shutdown the process
- on exit, but if Nvim fails to exit cleanly this
- could leave behind orphaned server processes.
- • {workspace_folders}? (`lsp.WorkspaceFolder[]`) List of workspace
- folders passed to the language server. For
- backwards compatibility rootUri and rootPath
- will be derived from the first workspace folder
- in this list. See `workspaceFolders` in the LSP
- spec.
- • {workspace_required}? (`boolean`) (default false) Server requires a
- workspace (no "single file" support). Note:
- Without a workspace, cross-file features
- (navigation, hover) may or may not work
- depending on the language server, even if the
- server doesn't require a workspace.
- • {capabilities}? (`lsp.ClientCapabilities`) Map overriding the
- default capabilities defined by
- |vim.lsp.protocol.make_client_capabilities()|,
- passed to the language server on
- initialization. Hint: use
- make_client_capabilities() and modify its
- result.
- • Note: To send an empty dictionary use
- |vim.empty_dict()|, else it will be encoded
- as an array.
- • {handlers}? (`table<string,function>`) Map of language
- server method names to |lsp-handler|
- • {settings}? (`lsp.LSPObject`) Map with language server
- specific settings. See the {settings} in
- |vim.lsp.Client|.
• {commands}? (`table<string,fun(command: lsp.Command, ctx: table)>`)
- Table that maps string of clientside commands
- to user-defined functions. Commands passed to
+ Client commands. Map of command names to
+ user-defined functions. Commands passed to
`start()` take precedence over the global
command registry. Each key must be a unique
command name, and the value is a function which
is called if any LSP action (code action, code
- lenses, ...) triggers the command.
+ lenses, …) triggers the command.
+ • {detached}? (`boolean`, default: true) Daemonize the server
+ process so that it runs in a separate process
+ group from Nvim. Nvim will shutdown the process
+ on exit, but if Nvim fails to exit cleanly this
+ could leave behind orphaned server processes.
+ • {flags}? (`table`) A table with flags for the client.
+ The current (experimental) flags are:
+ • {allow_incremental_sync}? (`boolean`,
+ default: `true`) Allow using incremental sync
+ for buffer edits
+ • {debounce_text_changes} (`integer`, default:
+ `150`) Debounce `didChange` notifications to
+ the server by the given number in
+ milliseconds. No debounce occurs if `nil`.
+ • {exit_timeout} (`integer|false`, default:
+ `false`) Milliseconds to wait for server to
+ exit cleanly after sending the "shutdown"
+ request before sending kill -15. If set to
+ false, nvim exits immediately after sending
+ the "shutdown" request to the server.
+ • {get_language_id}? (`fun(bufnr: integer, filetype: string): string`)
+ Language ID as string. Defaults to the buffer
+ filetype.
+ • {handlers}? (`table<string,function>`) Map of LSP method
+ names to |lsp-handler|s.
• {init_options}? (`lsp.LSPObject`) Values to pass in the
initialization request as
`initializationOptions`. See `initialize` in
the LSP spec.
- • {name}? (`string`, default: client-id) Name in log
- messages.
- • {get_language_id}? (`fun(bufnr: integer, filetype: string): string`)
- Language ID as string. Defaults to the buffer
- filetype.
+ • {name}? (`string`) (default: client-id) Name in logs
+ and user messages.
• {offset_encoding}? (`'utf-8'|'utf-16'|'utf-32'`) Called "position
- encoding" in LSP spec, the encoding that the
- LSP server expects. Client does not verify this
- is correct.
+ encoding" in LSP spec. The encoding that the
+ LSP server expects, used for communication. Not
+ validated. Can be modified in `on_init` before
+ text is sent to the server.
+ • {on_attach}? (`elem_or_list<fun(client: vim.lsp.Client, bufnr: integer)>`)
+ Callback invoked when client attaches to a
+ buffer.
• {on_error}? (`fun(code: integer, err: string)`) Callback
invoked when the client operation throws an
error. `code` is a number describing the error.
@@ -1385,13 +1377,12 @@ Lua module: vim.lsp.client *lsp-client*
possible errors. Use
`vim.lsp.rpc.client_errors[code]` to get
human-friendly name.
- • {before_init}? (`fun(params: lsp.InitializeParams, config: vim.lsp.ClientConfig)`)
- Callback invoked before the LSP "initialize"
- phase, where `params` contains the parameters
- being sent to the server and `config` is the
- config that was passed to |vim.lsp.start()|.
- You can use this to modify parameters before
- they are sent.
+ • {on_exit}? (`elem_or_list<fun(code: integer, signal: integer, client_id: integer)>`)
+ Callback invoked on client exit.
+ • code: exit code of the process
+ • signal: number describing the signal used to
+ terminate (if any)
+ • client_id: client handle
• {on_init}? (`elem_or_list<fun(client: vim.lsp.Client, init_result: lsp.InitializeResult)>`)
Callback invoked after LSP "initialize", where
`result` is a table of `capabilities` and
@@ -1401,36 +1392,30 @@ Lua module: vim.lsp.client *lsp-client*
You can only modify the
`client.offset_encoding` here before any
notifications are sent.
- • {on_exit}? (`elem_or_list<fun(code: integer, signal: integer, client_id: integer)>`)
- Callback invoked on client exit.
- • code: exit code of the process
- • signal: number describing the signal used to
- terminate (if any)
- • client_id: client handle
- • {on_attach}? (`elem_or_list<fun(client: vim.lsp.Client, bufnr: integer)>`)
- Callback invoked when client attaches to a
- buffer.
- • {trace}? (`'off'|'messages'|'verbose'`, default: "off")
- Passed directly to the language server in the
- initialize request. Invalid/empty values will
- • {flags}? (`table`) A table with flags for the client.
- The current (experimental) flags are:
- • {allow_incremental_sync}? (`boolean`,
- default: `true`) Allow using incremental sync
- for buffer edits
- • {debounce_text_changes} (`integer`, default:
- `150`) Debounce `didChange` notifications to
- the server by the given number in
- milliseconds. No debounce occurs if `nil`.
- • {exit_timeout} (`integer|false`, default:
- `false`) Milliseconds to wait for server to
- exit cleanly after sending the "shutdown"
- request before sending kill -15. If set to
- false, nvim exits immediately after sending
- the "shutdown" request to the server.
• {root_dir}? (`string`) Directory where the LSP server will
base its workspaceFolders, rootUri, and
rootPath on initialization.
+ • {settings}? (`lsp.LSPObject`) Map of language
+ server-specific settings, decided by the
+ client. Sent to the LS if requested via
+ `workspace/configuration`. Keys are
+ case-sensitive.
+ • {trace}? (`'off'|'messages'|'verbose'`, default: "off")
+ Passed directly to the language server in the
+ initialize request. Invalid/empty values will
+ • {workspace_folders}? (`lsp.WorkspaceFolder[]`) List of workspace
+ folders passed to the language server. For
+ backwards compatibility rootUri and rootPath
+ are derived from the first workspace folder in
+ this list. Can be `null` if the client supports
+ workspace folders but none are configured. See
+ `workspaceFolders` in LSP spec.
+ • {workspace_required}? (`boolean`) (default false) Server requires a
+ workspace (no "single file" support). Note:
+ Without a workspace, cross-file features
+ (navigation, hover) may or may not work
+ depending on the language server, even if the
+ server doesn't require a workspace.
Client:cancel_request({id}) *Client:cancel_request()*
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
@@ -171,7 +171,7 @@ added. But visually, this small bit of sugar gets reasonably close to a
*lua-regex*
Lua intentionally does not support regular expressions, instead it has limited
-|lua-patterns| which avoid the performance pitfalls of extended regex. Lua
+|lua-pattern|s which avoid the performance pitfalls of extended regex. Lua
scripts can also use Vim regex via |vim.regex()|.
Examples: >lua
@@ -2024,7 +2024,7 @@ vim.gsplit({s}, {sep}, {opts}) *vim.gsplit()*
See also: ~
• |string.gmatch()|
• |vim.split()|
- • |lua-patterns|
+ • |lua-pattern|s
• https://www.lua.org/pil/20.2.html
• http://lua-users.org/wiki/StringLibraryTutorial
@@ -2117,7 +2117,7 @@ vim.list_slice({list}, {start}, {finish}) *vim.list_slice()*
(`any[]`) Copy of table sliced from start to finish (inclusive)
vim.pesc({s}) *vim.pesc()*
- Escapes magic chars in |lua-patterns|.
+ Escapes magic chars in |lua-pattern|s.
Parameters: ~
• {s} (`string`) String to escape
@@ -2372,7 +2372,7 @@ vim.trim({s}) *vim.trim()*
(`string`) String with whitespace removed from its beginning and end
See also: ~
- • |lua-patterns|
+ • |lua-pattern|s
• https://www.lua.org/pil/20.2.html
*vim.validate()*
@@ -2672,7 +2672,7 @@ vim.filetype.add({filetypes}) *vim.filetype.add()*
Filetype mappings can be added either by extension or by filename (either
the "tail" or the full file path). The full file path is checked first,
followed by the file name. If a match is not found using the filename,
- then the filename is matched against the list of |lua-patterns| (sorted by
+ then the filename is matched against the list of |lua-pattern|s (sorted by
priority) until a match is found. Lastly, if pattern matching does not
find a filetype, then the file extension is used.
diff --git a/runtime/doc/luaref.txt b/runtime/doc/luaref.txt
@@ -4150,7 +4150,7 @@ string.upper({s}) *string.upper()*
locale.
------------------------------------------------------------------------------
-5.4.1 Patterns *lua-pattern* *lua-patterns*
+5.4.1 Patterns *lua-pattern*
A character class is used to represent a set of characters. The following
combinations are allowed in describing a character class:
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
@@ -120,7 +120,7 @@ The following predicates are built in:
match.
`lua-match?` *treesitter-predicate-lua-match?*
- Match |lua-patterns| against the text corresponding to a node,
+ Match |lua-pattern|s against the text corresponding to a node,
similar to `match?`
`any-lua-match?` *treesitter-predicate-any-lua-match?*
diff --git a/runtime/lua/vim/filetype.lua b/runtime/lua/vim/filetype.lua
@@ -2635,7 +2635,7 @@ end
--- Filetype mappings can be added either by extension or by filename (either
--- the "tail" or the full file path). The full file path is checked first,
--- followed by the file name. If a match is not found using the filename, then
---- the filename is matched against the list of |lua-patterns| (sorted by priority)
+--- the filename is matched against the list of |lua-pattern|s (sorted by priority)
--- until a match is found. Lastly, if pattern matching does not find a
--- filetype, then the file extension is used.
---
diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua
@@ -278,25 +278,24 @@ end
--- See `cmd` in [vim.lsp.ClientConfig].
--- @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, then the client will attach to all filetypes.
+--- Filetypes the client will attach to, if activated by `vim.lsp.enable()`. If not provided, the
+--- client will attach to all filetypes.
--- @field filetypes? 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.
---- @field root_markers? string[]
+--- Predicate which decides if a client should be re-used. Used on all running clients. The default
+--- 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 must be called to provide root_dir as a string. LSP will not be activated for the buffer
---- unless `on_dir` is called; thus a `root_dir()` function can dynamically decide whether to
---- activate (or skip) LSP per-buffer. See example at |vim.lsp.enable()|.
+--- 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()|.
--- @field root_dir? string|fun(bufnr: integer, on_dir:fun(root_dir?:string))
---
---- Predicate used to decide if a client should be re-used. Used on all
---- running clients. The default implementation re-uses a client if name and
---- root_dir matches.
---- @field reuse_client? fun(client: vim.lsp.Client, config: vim.lsp.ClientConfig): boolean
+--- Directory markers (e.g. ".git/", "package.json") used to decide `root_dir`. Unused if `root_dir`
+--- is provided.
+--- @field root_markers? string[]
--- Sets the default configuration for an LSP client (or _all_ clients if the special name "*" is
--- used).
diff --git a/runtime/lua/vim/lsp/client.lua b/runtime/lua/vim/lsp/client.lua
@@ -30,6 +30,19 @@ local validate = vim.validate
--- @field exit_timeout integer|false
--- @class vim.lsp.ClientConfig
+---
+--- Callback invoked before the LSP "initialize" phase, where `params` contains the parameters
+--- being sent to the server and `config` is the config that was passed to |vim.lsp.start()|.
+--- You can use this to modify parameters before they are sent.
+--- @field before_init? fun(params: lsp.InitializeParams, config: vim.lsp.ClientConfig)
+---
+--- Map overriding the default capabilities defined by |vim.lsp.protocol.make_client_capabilities()|,
+--- passed to the language server on initialization. Hint: use make_client_capabilities() and modify
+--- its result.
+--- - Note: To send an empty dictionary use |vim.empty_dict()|, else it will be encoded as an
+--- 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
@@ -43,75 +56,59 @@ local validate = vim.validate
--- (default: cwd)
--- @field cmd_cwd? string
---
---- Environment flags to pass to the LSP on spawn.
---- Must be specified using a table.
---- Non-string values are coerced to string.
+--- Environment variables passed to the LSP process on spawn. Non-string values are coerced to
+--- string.
--- Example:
--- ```lua
---- { PORT = 8080; HOST = "0.0.0.0"; }
+--- { PORT = 8080; HOST = '0.0.0.0'; }
--- ```
--- @field cmd_env? table
---
+--- Client commands. Map of command names to user-defined functions. Commands passed to `start()`
+--- take precedence over the global command registry. Each key must be a unique command name, and
+--- the value is a function which is called if any LSP action (code action, code lenses, …) triggers
+--- the command.
+--- @field commands? table<string,fun(command: lsp.Command, ctx: table)>
+---
--- Daemonize the server process so that it runs in a separate process group from Nvim.
--- Nvim will shutdown the process on exit, but if Nvim fails to exit cleanly this could leave
--- behind orphaned server processes.
--- (default: true)
--- @field detached? boolean
---
---- List of workspace folders passed to the language server.
---- For backwards compatibility rootUri and rootPath will be derived from the first workspace
---- folder in this list. See `workspaceFolders` in the LSP spec.
---- @field workspace_folders? lsp.WorkspaceFolder[]
----
---- (default false) Server requires a workspace (no "single file" support). Note: Without
---- a workspace, cross-file features (navigation, hover) may or may not work depending on the
---- language server, even if the server doesn't require a workspace.
---- @field workspace_required? boolean
+--- A table with flags for the client. The current (experimental) flags are:
+--- @field flags? vim.lsp.Client.Flags
---
---- Map overriding the default capabilities defined by |vim.lsp.protocol.make_client_capabilities()|,
---- passed to the language server on initialization. Hint: use make_client_capabilities() and modify
---- its result.
---- - Note: To send an empty dictionary use |vim.empty_dict()|, else it will be encoded as an
---- array.
---- @field capabilities? lsp.ClientCapabilities
+--- Language ID as string. Defaults to the buffer filetype.
+--- @field get_language_id? fun(bufnr: integer, filetype: string): string
---
---- Map of language server method names to |lsp-handler|
+--- Map of LSP method names to |lsp-handler|s.
--- @field handlers? table<string,function>
---
---- Map with language server specific settings.
---- See the {settings} in |vim.lsp.Client|.
---- @field settings? lsp.LSPObject
----
---- Table that maps string of clientside commands to user-defined functions.
---- Commands passed to `start()` take precedence over the global command registry. Each key
---- must be a unique command name, and the value is a function which is called if any LSP action
---- (code action, code lenses, ...) triggers the command.
---- @field commands? table<string,fun(command: lsp.Command, ctx: table)>
----
--- Values to pass in the initialization request as `initializationOptions`. See `initialize` in
--- the LSP spec.
--- @field init_options? lsp.LSPObject
---
---- Name in log messages.
---- (default: client-id)
+--- (default: client-id) Name in logs and user messages.
--- @field name? string
---
---- Language ID as string. Defaults to the buffer filetype.
---- @field get_language_id? fun(bufnr: integer, filetype: string): string
----
---- Called "position encoding" in LSP spec, the encoding that the LSP server expects.
---- Client does not verify this is correct.
+--- Called "position encoding" in LSP spec. The encoding that the LSP server expects, used for
+--- communication. Not validated. Can be modified in `on_init` before text is sent to the server.
--- @field offset_encoding? 'utf-8'|'utf-16'|'utf-32'
---
+--- Callback invoked when client attaches to a buffer.
+--- @field on_attach? elem_or_list<fun(client: vim.lsp.Client, bufnr: integer)>
+---
--- Callback invoked when the client operation throws an error. `code` is a number describing the error.
--- Other arguments may be passed depending on the error kind. See `vim.lsp.rpc.client_errors`
--- for possible errors. Use `vim.lsp.rpc.client_errors[code]` to get human-friendly name.
--- @field on_error? fun(code: integer, err: string)
---
---- Callback invoked before the LSP "initialize" phase, where `params` contains the parameters
---- being sent to the server and `config` is the config that was passed to |vim.lsp.start()|.
---- You can use this to modify parameters before they are sent.
---- @field before_init? fun(params: lsp.InitializeParams, config: vim.lsp.ClientConfig)
+--- Callback invoked on client exit.
+--- - code: exit code of the process
+--- - signal: number describing the signal used to terminate (if any)
+--- - client_id: client handle
+--- @field on_exit? elem_or_list<fun(code: integer, signal: integer, client_id: integer)>
---
--- Callback invoked after LSP "initialize", where `result` is a table of `capabilities` and
--- anything else the server may send. For example, clangd sends `init_result.offsetEncoding` if
@@ -119,49 +116,69 @@ local validate = vim.validate
--- here before any notifications are sent.
--- @field on_init? elem_or_list<fun(client: vim.lsp.Client, init_result: lsp.InitializeResult)>
---
---- Callback invoked on client exit.
---- - code: exit code of the process
---- - signal: number describing the signal used to terminate (if any)
---- - client_id: client handle
---- @field on_exit? elem_or_list<fun(code: integer, signal: integer, client_id: integer)>
+--- Directory where the LSP server will base its workspaceFolders, rootUri, and rootPath on initialization.
+--- @field root_dir? string
---
---- Callback invoked when client attaches to a buffer.
---- @field on_attach? elem_or_list<fun(client: vim.lsp.Client, bufnr: integer)>
+--- Map of language server-specific settings, decided by the client. Sent to the LS if requested via
+--- `workspace/configuration`. Keys are case-sensitive.
+--- @field settings? lsp.LSPObject
---
--- Passed directly to the language server in the initialize request. Invalid/empty values will
--- (default: "off")
--- @field trace? 'off'|'messages'|'verbose'
---
---- A table with flags for the client. The current (experimental) flags are:
---- @field flags? vim.lsp.Client.Flags
+--- List of workspace folders passed to the language server. For backwards compatibility rootUri and
+--- rootPath are derived from the first workspace folder in this list. Can be `null` if the client
+--- supports workspace folders but none are configured. See `workspaceFolders` in LSP spec.
+--- @field workspace_folders? lsp.WorkspaceFolder[]
---
---- Directory where the LSP server will base its workspaceFolders, rootUri, and rootPath on initialization.
---- @field root_dir? string
+--- (default false) Server requires a workspace (no "single file" support). Note: Without
+--- a workspace, cross-file features (navigation, hover) may or may not work depending on the
+--- language server, even if the server doesn't require a workspace.
+--- @field workspace_required? boolean
--- @class vim.lsp.Client.Progress: vim.Ringbuf<{token: integer|string, value: any}>
--- @field pending table<lsp.ProgressToken,lsp.LSPAny>
--- @class vim.lsp.Client
---
+--- @field attached_buffers table<integer,true>
+---
+--- Capabilities provided by the client (editor or tool), at startup.
+--- @field capabilities lsp.ClientCapabilities
+---
+--- Client commands. See [vim.lsp.ClientConfig].
+--- @field commands table<string,fun(command: lsp.Command, ctx: table)>
+---
+--- Copy of the config passed to |vim.lsp.start()|.
+--- @field config vim.lsp.ClientConfig
+---
+--- Capabilities provided at runtime (after startup).
+--- @field dynamic_capabilities lsp.DynamicCapabilities
+---
+--- A table with flags for the client. The current (experimental) flags are:
+--- @field flags vim.lsp.Client.Flags
+---
+--- See [vim.lsp.ClientConfig].
+--- @field get_language_id fun(bufnr: integer, filetype: string): string
+---
+--- See [vim.lsp.ClientConfig].
+--- @field handlers table<string,lsp.Handler>
+---
--- The id allocated to the client.
--- @field id integer
---
---- If a name is specified on creation, that will be used. Otherwise it is just
---- the client id. This is used for logs and messages.
---- @field name string
+--- @field initialized true?
---
---- RPC client object, for low level interaction with the client.
---- See |vim.lsp.rpc.start()|.
---- @field rpc vim.lsp.rpc.PublicClient
+--- See [vim.lsp.ClientConfig].
+--- @field name string
---
---- Called "position encoding" in LSP spec,
---- the encoding used for communicating with the server.
---- You can modify this in the `config`'s `on_init` method
---- before text is sent to the server.
+--- See [vim.lsp.ClientConfig].
--- @field offset_encoding string
---
---- The handlers used by the client as described in |lsp-handler|.
---- @field handlers table<string,lsp.Handler>
+--- A ring buffer (|vim.ringbuf()|) containing progress messages
+--- sent by the server.
+--- @field progress vim.lsp.Client.Progress
---
--- The current pending requests in flight to the server. Entries are key-value
--- pairs with the key being the request id while the value is a table with
@@ -171,34 +188,25 @@ local validate = vim.validate
--- are received from the server.
--- @field requests table<integer,{ type: string, bufnr: integer, method: string}?>
---
---- copy of the table that was passed by the user
---- to |vim.lsp.start()|.
---- @field config vim.lsp.ClientConfig
+--- See [vim.lsp.ClientConfig].
+--- @field root_dir string?
+---
+--- RPC client object, for low level interaction with the client.
+--- See |vim.lsp.rpc.start()|.
+--- @field rpc vim.lsp.rpc.PublicClient
---
---- Response from the server sent on `initialize` describing the server's
---- capabilities.
+--- Response from the server sent on `initialize` describing the server's capabilities.
--- @field server_capabilities lsp.ServerCapabilities?
---
---- Response from the server sent on `initialize` describing information about
---- the server.
+--- Response from the server sent on `initialize` describing server information (e.g. version).
--- @field server_info lsp.ServerInfo?
---
---- A ring buffer (|vim.ringbuf()|) containing progress messages
---- sent by the server.
---- @field progress vim.lsp.Client.Progress
----
---- @field initialized true?
+--- See [vim.lsp.ClientConfig].
+--- @field settings lsp.LSPObject
---
---- The workspace folders configured in the client when the server starts.
---- This property is only available if the client supports workspace folders.
---- It can be `null` if the client supports workspace folders but none are
---- configured.
+--- See [vim.lsp.ClientConfig].
--- @field workspace_folders lsp.WorkspaceFolder[]?
---- @field root_dir string?
---
---- @field attached_buffers table<integer,true>
----
---- @field private _log_prefix string
---
--- Track this so that we can escalate automatically if we've already tried a
--- graceful shutdown
@@ -208,26 +216,8 @@ local validate = vim.validate
--- trace = "off" | "messages" | "verbose";
--- @field private _trace 'off'|'messages'|'verbose'
---
---- Table of command name to function which is called if any LSP action
---- (code action, code lenses, ...) triggers the command.
---- Client commands take precedence over the global command registry.
---- @field commands table<string,fun(command: lsp.Command, ctx: table)>
----
---- Map with language server specific settings. These are returned to the
---- language server if requested via `workspace/configuration`. Keys are
---- case-sensitive.
---- @field settings lsp.LSPObject
----
---- A table with flags for the client. The current (experimental) flags are:
---- @field flags vim.lsp.Client.Flags
----
---- @field get_language_id fun(bufnr: integer, filetype: string): string
----
---- The capabilities provided by the client (editor or tool)
---- @field capabilities lsp.ClientCapabilities
--- @field private registrations table<string,lsp.Registration[]>
---- @field dynamic_capabilities lsp.DynamicCapabilities
----
+--- @field private _log_prefix string
--- @field private _before_init_cb? vim.lsp.client.before_init_cb
--- @field private _on_attach_cbs vim.lsp.client.on_attach_cb[]
--- @field private _on_init_cbs vim.lsp.client.on_init_cb[]
diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
@@ -95,7 +95,7 @@ end
---
--- @see |string.gmatch()|
--- @see |vim.split()|
---- @see |lua-patterns|
+--- @see |lua-pattern|s
--- @see https://www.lua.org/pil/20.2.html
--- @see http://lua-users.org/wiki/StringLibraryTutorial
---
@@ -784,7 +784,7 @@ end
--- Trim whitespace (Lua pattern "%s") from both sides of a string.
---
----@see |lua-patterns|
+---@see |lua-pattern|s
---@see https://www.lua.org/pil/20.2.html
---@param s string String to trim
---@return string String with whitespace removed from its beginning and end
@@ -793,7 +793,7 @@ function vim.trim(s)
return s:match('^%s*(.*%S)') or ''
end
---- Escapes magic chars in |lua-patterns|.
+--- Escapes magic chars in |lua-pattern|s.
---
---@see https://github.com/rxi/lume
---@param s string String to escape
