mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-09-07 03:48:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc(lsp): format arguments to start_client() (#21980)

Browse Source 
docs(lsp): format arguments to start_client()
This commit is contained in:
Lewis Russell
2023-01-24 18:04:15 +00:00
committed by GitHub
parent cd613712b1
commit 9166116c67
2 changed files with 195 additions and 206 deletions
Download Patch File Download Diff File Expand all files Collapse all files

204
runtime/doc/lsp.txt
View File

@@ -832,127 +832,117 @@ start({config}, {opts}) *vim.lsp.start()*
start_client({config}) *vim.lsp.start_client()* start_client({config}) *vim.lsp.start_client()*
Starts and initializes a client with the given configuration. Starts and initializes a client with the given configuration.
Parameter `cmd` is required. Field `cmd` in {config} is required.
The following parameters describe fields in the {config} table.
Parameters: ~ Parameters: ~
• {cmd} (table|string|fun(dispatchers: table):table) • {config} (table) Configuration for the server:
command string or list treated like |jobstart()|. • cmd: (table|string|fun(dispatchers: table):table) command
The command must launch the language server string or list treated like |jobstart()|. The command must
process. `cmd` can also be a function that launch the language server process. `cmd` can also be a
creates an RPC client. The function receives a function that creates an RPC client. The function receives
dispatchers table and must return a table with a dispatchers table and must return a table with the
the functions `request`, `notify`, `is_closing` functions `request`, `notify`, `is_closing` and
and `terminate` See |vim.lsp.rpc.request()| and `terminate` See |vim.lsp.rpc.request()| and
|vim.lsp.rpc.notify()| For TCP there is a |vim.lsp.rpc.notify()| For TCP there is a built-in rpc
built-in rpc client factory: client factory: |vim.lsp.rpc.connect()|
|vim.lsp.rpc.connect()| • cmd_cwd: (string, default=|getcwd()|) Directory to launch
• {cmd_cwd} (string, default=|getcwd()|) Directory to launch
the `cmd` process. Not related to `root_dir`. the `cmd` process. Not related to `root_dir`.
• {cmd_env} (table) Environment flags to pass to the LSP on • cmd_env: (table) Environment flags to pass to the LSP on
spawn. Can be specified using keys like a map or spawn. Can be specified using keys like a map or as a list
as a list with `k=v` pairs or both. Non-string values are coerced to with `k=v` pairs or both. Non-string values are coerced to string.
string. Example: > Example: >
{ "PRODUCTION=true"; "TEST=123"; PORT = 8080; HOST = "0.0.0.0"; } { "PRODUCTION=true"; "TEST=123"; PORT = 8080; HOST = "0.0.0.0"; }
< <
• {detached} (boolean, default true) Daemonize the server • detached: (boolean, default true) Daemonize the server
process so that it runs in a separate process process so that it runs in a separate process group from
group from Nvim. Nvim will shutdown the process Nvim. Nvim will shutdown the process on exit, but if Nvim
on exit, but if Nvim fails to exit cleanly this fails to exit cleanly this could leave behind orphaned
could leave behind orphaned server processes. server processes.
• {workspace_folders} (table) List of workspace folders passed to the • workspace_folders: (table) List of workspace folders
language server. For backwards compatibility passed to the language server. For backwards compatibility
rootUri and rootPath will be derived from the rootUri and rootPath will be derived from the first
first workspace folder in this list. See workspace folder in this list. See `workspaceFolders` in
`workspaceFolders` in the LSP spec. the LSP spec.
• {capabilities} Map overriding the default capabilities defined • capabilities: Map overriding the default capabilities
by |vim.lsp.protocol.make_client_capabilities()|, defined by |vim.lsp.protocol.make_client_capabilities()|,
passed to the language server on initialization. passed to the language server on initialization. Hint: use
Hint: use make_client_capabilities() and modify make_client_capabilities() and modify its result.
its result.
• Note: To send an empty dictionary use • Note: To send an empty dictionary use
`{[vim.type_idx]=vim.types.dictionary}`, else `{[vim.type_idx]=vim.types.dictionary}`, else it will be
it will be encoded as an array. encoded as an array.
• {handlers} Map of language server method names to
• handlers: Map of language server method names to
|lsp-handler| |lsp-handler|
• {settings} Map with language server specific settings. These • settings: Map with language server specific settings.
are returned to the language server if requested These are returned to the language server if requested via
via `workspace/configuration`. Keys are `workspace/configuration`. Keys are case-sensitive.
case-sensitive. • commands: table Table that maps string of clientside
• {commands} (table) Table that maps string of clientside commands to user-defined functions. Commands passed to
commands to user-defined functions. Commands start_client take precedence over the global command
passed to start_client take precedence over the registry. Each key must be a unique command name, and the
global command registry. Each key must be a value is a function which is called if any LSP action
unique command name, and the value is a function (code action, code lenses, ...) triggers the command.
which is called if any LSP action (code action, • init_options Values to pass in the initialization request
code lenses, ...) triggers the command. as `initializationOptions`. See `initialize` in the LSP
• {init_options} Values to pass in the initialization request as spec.
`initializationOptions`. See `initialize` in the • name: (string, default=client-id) Name in log messages.
LSP spec. • get_language_id: function(bufnr, filetype) -> language ID
• {name} (string, default=client-id) Name in log messages. as string. Defaults to the filetype.
• {get_language_id} function(bufnr, filetype) -> language ID as • offset_encoding: (default="utf-16") One of "utf-8",
string. Defaults to the filetype. "utf-16", or "utf-32" which is the encoding that the LSP
• {offset_encoding} (default="utf-16") One of "utf-8", "utf-16", or server expects. Client does not verify this is correct.
"utf-32" which is the encoding that the LSP • on_error: Callback with parameters (code, ...), invoked
server expects. Client does not verify this is when the client operation throws an error. `code` is a
correct. number describing the error. Other arguments may be passed
• {on_error} Callback with parameters (code, ...), invoked depending on the error kind. See
when the client operation throws an error. `code` `vim.lsp.rpc.client_errors` for possible errors. Use
is a number describing the error. Other arguments `vim.lsp.rpc.client_errors[code]` to get human-friendly
may be passed depending on the error kind. See name.
`vim.lsp.rpc.client_errors` for possible errors. • before_init: Callback with parameters (initialize_params,
Use `vim.lsp.rpc.client_errors[code]` to get config) invoked before the LSP "initialize" phase, where
human-friendly name. `params` contains the parameters being sent to the server
• {before_init} Callback with parameters (initialize_params, and `config` is the config that was passed to
config) invoked before the LSP "initialize" |vim.lsp.start_client()|. You can use this to modify
phase, where `params` contains the parameters parameters before they are sent.
being sent to the server and `config` is the • on_init: Callback (client, initialize_result) invoked
config that was passed to after LSP "initialize", where `result` is a table of
|vim.lsp.start_client()|. You can use this to `capabilities` and anything else the server may send. For
modify parameters before they are sent. example, clangd sends `initialize_result.offsetEncoding`
• {on_init} Callback (client, initialize_result) invoked if `capabilities.offsetEncoding` was sent to it. You can
after LSP "initialize", where `result` is a table only modify the `client.offset_encoding` here before any
of `capabilities` and anything else the server notifications are sent. Most language servers expect to be
may send. For example, clangd sends sent client specified settings after initialization.
`initialize_result.offsetEncoding` if Neovim does not make this assumption. A
`capabilities.offsetEncoding` was sent to it. You `workspace/didChangeConfiguration` notification should be
can only modify the `client.offset_encoding` here sent to the server during on_init.
before any notifications are sent. Most language • on_exit Callback (code, signal, client_id) invoked on
servers expect to be sent client specified
settings after initialization. Neovim does not
make this assumption. A
`workspace/didChangeConfiguration` notification
should be sent to the server during on_init.
• {on_exit} Callback (code, signal, client_id) invoked on
client exit. client exit.
• code: exit code of the process • code: exit code of the process
• signal: number describing the signal used to • signal: number describing the signal used to terminate
terminate (if any) (if any)
• client_id: client handle • client_id: client handle
• {on_attach} Callback (client, bufnr) invoked when client
• on_attach: Callback (client, bufnr) invoked when client
attaches to a buffer. attaches to a buffer.
• {trace} "off" | "messages" | "verbose" | nil passed • trace: ("off" | "messages" | "verbose" | nil) passed
directly to the language server in the initialize directly to the language server in the initialize request.
request. Invalid/empty values will default to Invalid/empty values will default to "off"
"off" • flags: A table with flags for the client. The current
• {flags} A table with flags for the client. The current
(experimental) flags are: (experimental) flags are:
• allow_incremental_sync (bool, default true): • allow_incremental_sync (bool, default true): Allow using
Allow using incremental sync for buffer edits incremental sync for buffer edits
• debounce_text_changes (number, default 150): • debounce_text_changes (number, default 150): Debounce
Debounce didChange notifications to the server didChange notifications to the server by the given
by the given number in milliseconds. No number in milliseconds. No debounce occurs if nil
debounce occurs if nil
• exit_timeout (number|boolean, default false): • exit_timeout (number|boolean, default false):
Milliseconds to wait for server to exit cleanly Milliseconds to wait for server to exit cleanly after
after sending the "shutdown" request before sending the "shutdown" request before sending kill -15.
sending kill -15. If set to false, nvim exits If set to false, nvim exits immediately after sending
immediately after sending the "shutdown" the "shutdown" request to the server.
request to the server.
• {root_dir} (string) Directory where the LSP server will base • root_dir: (string) Directory where the LSP server will
its workspaceFolders, rootUri, and rootPath on base its workspaceFolders, rootUri, and rootPath on
initialization. initialization.
Return: ~ Return: ~

49
runtime/lua/vim/lsp.lua
View File

@@ -897,12 +897,10 @@ end
-- --
--- Starts and initializes a client with the given configuration. --- Starts and initializes a client with the given configuration.
--- ---
--- Parameter `cmd` is required. --- Field `cmd` in {config} is required.
--- ---
--- The following parameters describe fields in the {config} table. ---@param config (table) Configuration for the server:
--- --- - cmd: (table|string|fun(dispatchers: table):table) command string or
---
---@param cmd: (table|string|fun(dispatchers: table):table) command string or
--- list treated like |jobstart()|. The command must launch the language server --- list treated like |jobstart()|. The command must launch the language server
--- process. `cmd` can also be a function that creates an RPC client. --- process. `cmd` can also be a function that creates an RPC client.
--- The function receives a dispatchers table and must return a table with the --- The function receives a dispatchers table and must return a table with the
@@ -910,10 +908,10 @@ end
--- See |vim.lsp.rpc.request()| and |vim.lsp.rpc.notify()| --- See |vim.lsp.rpc.request()| and |vim.lsp.rpc.notify()|
--- For TCP there is a built-in rpc client factory: |vim.lsp.rpc.connect()| --- For TCP there is a built-in rpc client factory: |vim.lsp.rpc.connect()|
--- ---
---@param cmd_cwd: (string, default=|getcwd()|) Directory to launch --- - cmd_cwd: (string, default=|getcwd()|) Directory to launch
--- the `cmd` process. Not related to `root_dir`. --- the `cmd` process. Not related to `root_dir`.
--- ---
---@param cmd_env: (table) Environment flags to pass to the LSP on --- - cmd_env: (table) Environment flags to pass to the LSP on
--- spawn. Can be specified using keys like a map or as a list with `k=v` --- spawn. Can be specified using keys like a map or as a list with `k=v`
--- pairs or both. Non-string values are coerced to string. --- pairs or both. Non-string values are coerced to string.
--- Example: --- Example:
@@ -921,16 +919,16 @@ end
--- { "PRODUCTION=true"; "TEST=123"; PORT = 8080; HOST = "0.0.0.0"; } --- { "PRODUCTION=true"; "TEST=123"; PORT = 8080; HOST = "0.0.0.0"; }
--- </pre> --- </pre>
--- ---
---@param detached: (boolean, default true) Daemonize the server process so that it runs in a --- - 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 --- 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. --- exit cleanly this could leave behind orphaned server processes.
--- ---
---@param workspace_folders (table) List of workspace folders passed to the --- - workspace_folders: (table) List of workspace folders passed to the
--- language server. For backwards compatibility rootUri and rootPath will be --- language server. For backwards compatibility rootUri and rootPath will be
--- derived from the first workspace folder in this list. See `workspaceFolders` in --- derived from the first workspace folder in this list. See `workspaceFolders` in
--- the LSP spec. --- the LSP spec.
--- ---
---@param capabilities Map overriding the default capabilities defined by --- - capabilities: Map overriding the default capabilities defined by
--- |vim.lsp.protocol.make_client_capabilities()|, passed to the language --- |vim.lsp.protocol.make_client_capabilities()|, passed to the language
--- server on initialization. Hint: use make_client_capabilities() and modify --- server on initialization. Hint: use make_client_capabilities() and modify
--- its result. --- its result.
@@ -938,42 +936,42 @@ end
--- `{[vim.type_idx]=vim.types.dictionary}`, else it will be encoded as an --- `{[vim.type_idx]=vim.types.dictionary}`, else it will be encoded as an
--- array. --- array.
--- ---
---@param handlers Map of language server method names to |lsp-handler| --- - handlers: Map of language server method names to |lsp-handler|
--- ---
---@param settings Map with language server specific settings. These are --- - settings: Map with language server specific settings. These are
--- returned to the language server if requested via `workspace/configuration`. --- returned to the language server if requested via `workspace/configuration`.
--- Keys are case-sensitive. --- Keys are case-sensitive.
--- ---
---@param commands table Table that maps string of clientside commands to user-defined functions. --- - commands: table Table that maps string of clientside commands to user-defined functions.
--- Commands passed to start_client take precedence over the global command registry. Each key --- Commands passed to start_client 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 --- 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. --- (code action, code lenses, ...) triggers the command.
--- ---
---@param init_options Values to pass in the initialization request --- - init_options Values to pass in the initialization request
--- as `initializationOptions`. See `initialize` in the LSP spec. --- as `initializationOptions`. See `initialize` in the LSP spec.
--- ---
---@param name (string, default=client-id) Name in log messages. --- - name: (string, default=client-id) Name in log messages.
--- ---
---@param get_language_id function(bufnr, filetype) -> language ID as string. --- - get_language_id: function(bufnr, filetype) -> language ID as string.
--- Defaults to the filetype. --- Defaults to the filetype.
--- ---
---@param offset_encoding (default="utf-16") One of "utf-8", "utf-16", --- - offset_encoding: (default="utf-16") One of "utf-8", "utf-16",
--- or "utf-32" which is the encoding that the LSP server expects. Client does --- or "utf-32" which is the encoding that the LSP server expects. Client does
--- not verify this is correct. --- not verify this is correct.
--- ---
---@param on_error Callback with parameters (code, ...), invoked --- - on_error: Callback with parameters (code, ...), invoked
--- when the client operation throws an error. `code` is a number describing --- 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 --- the error. Other arguments may be passed depending on the error kind. See
--- `vim.lsp.rpc.client_errors` for possible errors. --- `vim.lsp.rpc.client_errors` for possible errors.
--- Use `vim.lsp.rpc.client_errors[code]` to get human-friendly name. --- Use `vim.lsp.rpc.client_errors[code]` to get human-friendly name.
--- ---
---@param before_init Callback with parameters (initialize_params, config) --- - before_init: Callback with parameters (initialize_params, config)
--- invoked before the LSP "initialize" phase, where `params` contains the --- invoked before the LSP "initialize" phase, where `params` contains the
--- parameters being sent to the server and `config` is the config that was --- parameters being sent to the server and `config` is the config that was
--- passed to |vim.lsp.start_client()|. You can use this to modify parameters before --- passed to |vim.lsp.start_client()|. You can use this to modify parameters before
--- they are sent. --- they are sent.
--- ---
---@param on_init Callback (client, initialize_result) invoked after LSP --- - on_init: Callback (client, initialize_result) invoked after LSP
--- "initialize", where `result` is a table of `capabilities` and anything else --- "initialize", where `result` is a table of `capabilities` and anything else
--- the server may send. For example, clangd sends --- the server may send. For example, clangd sends
--- `initialize_result.offsetEncoding` if `capabilities.offsetEncoding` was --- `initialize_result.offsetEncoding` if `capabilities.offsetEncoding` was
@@ -983,18 +981,19 @@ end
--- `workspace/didChangeConfiguration` notification should be sent --- `workspace/didChangeConfiguration` notification should be sent
--- to the server during on_init. --- to the server during on_init.
--- ---
---@param on_exit Callback (code, signal, client_id) invoked on client --- - on_exit Callback (code, signal, client_id) invoked on client
--- exit. --- exit.
--- - code: exit code of the process --- - code: exit code of the process
--- - signal: number describing the signal used to terminate (if any) --- - signal: number describing the signal used to terminate (if any)
--- - client_id: client handle --- - client_id: client handle
--- ---
---@param on_attach Callback (client, bufnr) invoked when client --- - on_attach: Callback (client, bufnr) invoked when client
--- attaches to a buffer. --- attaches to a buffer.
--- ---
---@param trace: "off" | "messages" | "verbose" | nil passed directly to the language --- - trace: ("off" | "messages" | "verbose" | nil) passed directly to the language
--- server in the initialize request. Invalid/empty values will default to "off" --- server in the initialize request. Invalid/empty values will default to "off"
---@param flags: A table with flags for the client. The current (experimental) flags are: ---
--- - flags: A table with flags for the client. The current (experimental) flags are:
--- - allow_incremental_sync (bool, default true): Allow using incremental sync for buffer edits --- - allow_incremental_sync (bool, default true): Allow using incremental sync for buffer edits
--- - debounce_text_changes (number, default 150): Debounce didChange --- - debounce_text_changes (number, default 150): Debounce didChange
--- notifications to the server by the given number in milliseconds. No debounce --- notifications to the server by the given number in milliseconds. No debounce
@@ -1003,7 +1002,7 @@ end
--- exit cleanly after sending the "shutdown" request before sending kill -15. --- 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. --- If set to false, nvim exits immediately after sending the "shutdown" request to the server.
--- ---
---@param root_dir string Directory where the LSP --- - root_dir: (string) Directory where the LSP
--- server will base its workspaceFolders, rootUri, and rootPath --- server will base its workspaceFolders, rootUri, and rootPath
--- on initialization. --- on initialization.
--- ---