From 9166116c6730ef1687f35b8c58653583d2c301c3 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Tue, 24 Jan 2023 18:04:15 +0000 Subject: [PATCH] doc(lsp): format arguments to start_client() (#21980) docs(lsp): format arguments to start_client() --- runtime/doc/lsp.txt | 226 +++++++++++++++++++--------------------- runtime/lua/vim/lsp.lua | 175 ++++++++++++++++--------------- 2 files changed, 195 insertions(+), 206 deletions(-) diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index 9757bc9693..215515a2d9 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -832,128 +832,118 @@ start({config}, {opts}) *vim.lsp.start()* start_client({config}) *vim.lsp.start_client()* Starts and initializes a client with the given configuration. - Parameter `cmd` is required. - - The following parameters describe fields in the {config} table. + Field `cmd` in {config} is required. Parameters: ~ - • {cmd} (table|string|fun(dispatchers: table):table) - command string or list treated like |jobstart()|. - The command must launch the language server - 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 functions `request`, `notify`, `is_closing` - and `terminate` See |vim.lsp.rpc.request()| and - |vim.lsp.rpc.notify()| For TCP there is a - built-in rpc client factory: - |vim.lsp.rpc.connect()| - • {cmd_cwd} (string, default=|getcwd()|) Directory to launch - the `cmd` process. Not related to `root_dir`. - • {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` pairs or both. Non-string values are coerced to - string. Example: > + • {config} (table) Configuration for the server: + • cmd: (table|string|fun(dispatchers: table):table) command + string or list treated like |jobstart()|. The command must + launch the language server 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 + functions `request`, `notify`, `is_closing` and + `terminate` See |vim.lsp.rpc.request()| and + |vim.lsp.rpc.notify()| For TCP there is a built-in rpc + client factory: |vim.lsp.rpc.connect()| + • cmd_cwd: (string, default=|getcwd()|) Directory to launch + the `cmd` process. Not related to `root_dir`. + • 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` pairs or both. Non-string values are coerced to string. + 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 - 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} (table) 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. - • {capabilities} 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.type_idx]=vim.types.dictionary}`, else - it will be encoded as an array. - • {handlers} Map of language server method names to - |lsp-handler| - • {settings} Map with language server specific settings. These - are returned to the language server if requested - via `workspace/configuration`. Keys are - case-sensitive. - • {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 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. - • {init_options} 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} function(bufnr, filetype) -> language ID as - string. Defaults to the filetype. - • {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 not verify this is - correct. - • {on_error} Callback with parameters (code, ...), 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. - • {before_init} Callback with parameters (initialize_params, - config) 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_client()|. You can use this to - modify parameters before they are sent. - • {on_init} Callback (client, initialize_result) invoked - after LSP "initialize", where `result` is a table - of `capabilities` and anything else the server - may send. For example, clangd sends - `initialize_result.offsetEncoding` if - `capabilities.offsetEncoding` was sent to it. You - can only modify the `client.offset_encoding` here - before any notifications are sent. Most language - 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. - • code: exit code of the process - • signal: number describing the signal used to - terminate (if any) - • client_id: client handle - • {on_attach} Callback (client, bufnr) invoked when client - attaches to a buffer. - • {trace} "off" | "messages" | "verbose" | nil passed - directly to the language server in the initialize - request. Invalid/empty values will default to - "off" - • {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 - • debounce_text_changes (number, default 150): - Debounce didChange notifications to the server - by the given number in milliseconds. No - debounce occurs if nil - • exit_timeout (number|boolean, 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. + • 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: (table) 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. + • capabilities: 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.type_idx]=vim.types.dictionary}`, else it will be + encoded as an array. + + • handlers: Map of language server method names to + |lsp-handler| + • settings: Map with language server specific settings. + These are returned to the language server if requested via + `workspace/configuration`. Keys are case-sensitive. + • 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 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. + • init_options 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: function(bufnr, filetype) -> language ID + as string. Defaults to the filetype. + • 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 not verify this is correct. + • on_error: Callback with parameters (code, ...), 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. + • before_init: Callback with parameters (initialize_params, + config) 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_client()|. You can use this to modify + parameters before they are sent. + • on_init: Callback (client, initialize_result) invoked + after LSP "initialize", where `result` is a table of + `capabilities` and anything else the server may send. For + example, clangd sends `initialize_result.offsetEncoding` + if `capabilities.offsetEncoding` was sent to it. You can + only modify the `client.offset_encoding` here before any + notifications are sent. Most language 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. + • code: exit code of the process + • signal: number describing the signal used to terminate + (if any) + • client_id: client handle + + • on_attach: Callback (client, bufnr) invoked when client + attaches to a buffer. + • trace: ("off" | "messages" | "verbose" | nil) passed + directly to the language server in the initialize request. + Invalid/empty values will default to "off" + • 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 + • debounce_text_changes (number, default 150): Debounce + didChange notifications to the server by the given + number in milliseconds. No debounce occurs if nil + • exit_timeout (number|boolean, 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. Return: ~ Client id. |vim.lsp.get_client_by_id()| Note: client may not be fully diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua index 134a009a72..c5392ac154 100644 --- a/runtime/lua/vim/lsp.lua +++ b/runtime/lua/vim/lsp.lua @@ -897,115 +897,114 @@ end -- --- 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 +--- list treated like |jobstart()|. The command must launch the language server +--- 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 +--- functions `request`, `notify`, `is_closing` and `terminate` +--- See |vim.lsp.rpc.request()| and |vim.lsp.rpc.notify()| +--- For TCP there is a built-in rpc client factory: |vim.lsp.rpc.connect()| --- +--- - cmd_cwd: (string, default=|getcwd()|) Directory to launch +--- the `cmd` process. Not related to `root_dir`. --- ----@param cmd: (table|string|fun(dispatchers: table):table) command string or ---- list treated like |jobstart()|. The command must launch the language server ---- 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 ---- functions `request`, `notify`, `is_closing` and `terminate` ---- See |vim.lsp.rpc.request()| and |vim.lsp.rpc.notify()| ---- For TCP there is a built-in rpc client factory: |vim.lsp.rpc.connect()| +--- - 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` +--- pairs or both. Non-string values are coerced to string. +--- Example: +--- 
+---                   { "PRODUCTION=true"; "TEST=123"; PORT = 8080; HOST = "0.0.0.0"; }
+---
--- ----@param cmd_cwd: (string, default=|getcwd()|) Directory to launch ---- the `cmd` process. Not related to `root_dir`. +--- - 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. --- ----@param 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` ---- pairs or both. Non-string values are coerced to string. ---- Example: ---- 
---- { "PRODUCTION=true"; "TEST=123"; PORT = 8080; HOST = "0.0.0.0"; }
----
+--- - workspace_folders: (table) 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. --- ----@param 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. +--- - capabilities: 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.type_idx]=vim.types.dictionary}`, else it will be encoded as an +--- array. --- ----@param workspace_folders (table) 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. +--- - handlers: Map of language server method names to |lsp-handler| --- ----@param capabilities 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.type_idx]=vim.types.dictionary}`, else it will be encoded as an ---- array. +--- - settings: Map with language server specific settings. These are +--- returned to the language server if requested via `workspace/configuration`. +--- Keys are case-sensitive. --- ----@param handlers Map of language server method names to |lsp-handler| +--- - 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 +--- 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. --- ----@param settings Map with language server specific settings. These are ---- returned to the language server if requested via `workspace/configuration`. ---- Keys are case-sensitive. +--- - init_options Values to pass in the initialization request +--- as `initializationOptions`. See `initialize` in the LSP spec. --- ----@param 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 ---- 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. +--- - name: (string, default=client-id) Name in log messages. --- ----@param init_options Values to pass in the initialization request ---- as `initializationOptions`. See `initialize` in the LSP spec. +--- - get_language_id: function(bufnr, filetype) -> language ID as string. +--- Defaults to the filetype. --- ----@param name (string, default=client-id) Name in log messages. +--- - 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 +--- not verify this is correct. --- ----@param get_language_id function(bufnr, filetype) -> language ID as string. ---- Defaults to the filetype. +--- - on_error: Callback with parameters (code, ...), 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. --- ----@param 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 ---- not verify this is correct. +--- - before_init: Callback with parameters (initialize_params, config) +--- 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_client()|. You can use this to modify parameters before +--- they are sent. --- ----@param on_error Callback with parameters (code, ...), 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. +--- - on_init: Callback (client, initialize_result) invoked after LSP +--- "initialize", where `result` is a table of `capabilities` and anything else +--- the server may send. For example, clangd sends +--- `initialize_result.offsetEncoding` if `capabilities.offsetEncoding` was +--- sent to it. You can only modify the `client.offset_encoding` here before +--- any notifications are sent. Most language 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. --- ----@param before_init Callback with parameters (initialize_params, config) ---- 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_client()|. You can use this to modify parameters before ---- they are sent. ---- ----@param on_init Callback (client, initialize_result) invoked after LSP ---- "initialize", where `result` is a table of `capabilities` and anything else ---- the server may send. For example, clangd sends ---- `initialize_result.offsetEncoding` if `capabilities.offsetEncoding` was ---- sent to it. You can only modify the `client.offset_encoding` here before ---- any notifications are sent. Most language 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. ---- ----@param on_exit Callback (code, signal, client_id) invoked on client +--- - on_exit Callback (code, signal, client_id) invoked on client --- exit. ---- - code: exit code of the process ---- - signal: number describing the signal used to terminate (if any) ---- - client_id: client handle +--- - code: exit code of the process +--- - signal: number describing the signal used to terminate (if any) +--- - client_id: client handle --- ----@param on_attach Callback (client, bufnr) invoked when client ---- attaches to a buffer. +--- - on_attach: Callback (client, bufnr) invoked when client +--- attaches to a buffer. --- ----@param trace: "off" | "messages" | "verbose" | nil passed directly to the language ---- 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: ---- - allow_incremental_sync (bool, default true): Allow using incremental sync for buffer edits ---- - debounce_text_changes (number, default 150): Debounce didChange ---- notifications to the server by the given number in milliseconds. No debounce ---- occurs if nil ---- - exit_timeout (number|boolean, 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. +--- - trace: ("off" | "messages" | "verbose" | nil) passed directly to the language +--- server in the initialize request. Invalid/empty values will default to "off" --- ----@param root_dir string Directory where the LSP ---- server will base its workspaceFolders, rootUri, and rootPath ---- on initialization. +--- - 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 +--- - debounce_text_changes (number, default 150): Debounce didChange +--- notifications to the server by the given number in milliseconds. No debounce +--- occurs if nil +--- - exit_timeout (number|boolean, 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. --- ---@returns Client id. |vim.lsp.get_client_by_id()| Note: client may not be --- fully initialized. Use `on_init` to do any actions once