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

docs(lsp): format arguments to start_client()

2 files changed, 218 insertions, 229 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.
-
-    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: >
-
-     { "PRODUCTION=true"; "TEST=123"; PORT = 8080; HOST = "0.0.0.0"; }
+    Field `cmd` in {config} is required.
+
+    Parameters: ~
+      • {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"; }
 <
-      • {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.
----
---- The following parameters describe fields in the {config} table.
----
----
----@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()|
----
----@param cmd_cwd: (string, default=|getcwd()|) Directory to launch
---- the `cmd` process. Not related to `root_dir`.
----
----@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:
---- <pre>
---- { "PRODUCTION=true"; "TEST=123"; PORT = 8080; HOST = "0.0.0.0"; }
---- </pre>
----
----@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.
----
----@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.
----
----@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.
----
----@param handlers Map of language server method names to |lsp-handler|
----
----@param settings Map with language server specific settings. These are
---- returned to the language server if requested via `workspace/configuration`.
---- Keys are case-sensitive.
----
----@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.
----
----@param init_options Values to pass in the initialization request
---- as `initializationOptions`. See `initialize` in the LSP spec.
----
----@param name (string, default=client-id) Name in log messages.
----
----@param get_language_id function(bufnr, filetype) -> language ID as string.
---- Defaults to the filetype.
----
----@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.
----
----@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.
----
----@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
+--- Field `cmd` in {config} is required.
+---
+---@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`.
+---
+--- - 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:
+---       <pre>
+---                   { "PRODUCTION=true"; "TEST=123"; PORT = 8080; HOST = "0.0.0.0"; }
+---       </pre>
+---
+--- - 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
----
----@param 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.
----
----@param root_dir string Directory where the LSP
---- server will base its workspaceFolders, rootUri, and rootPath
---- on initialization.
+---       - 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.
 ---
 ---@returns Client id. |vim.lsp.get_client_by_id()| Note: client may not be
 --- fully initialized. Use `on_init` to do any actions once