Merge remote-tracking branch 'upstream/master' into usermarksusermarks

1 files changed, 487 insertions, 462 deletions

diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 7fc0daa0ca..215515a2d9 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -33,40 +33,40 @@ Follow these steps to get LSP features:
 
   2. Configure the LSP client per language server.
      A minimal example:
->
+>lua
     vim.lsp.start({
       name = 'my-server-name',
       cmd = {'name-of-language-server-executable'},
       root_dir = vim.fs.dirname(vim.fs.find({'setup.py', 'pyproject.toml'}, { upward = true })[1]),
     })
 <
-     See |vim.lsp.start| for details.
+     See |vim.lsp.start()| for details.
 
   3. Configure keymaps and autocmds to utilize LSP features.
      See |lsp-config|.
-<
+
                                                         *lsp-config*
 
 Starting a LSP client will automatically report diagnostics via
-|vim.diagnostic|. Read |vim.diagnostic.config| to learn how to customize the
+|vim.diagnostic|. Read |vim.diagnostic.config()| to learn how to customize the
 display.
 
 It also sets some buffer options if the options are otherwise empty and if the
 language server supports the functionality.
 
-- |omnifunc| is set to |vim.lsp.omnifunc|. This allows to trigger completion
-  using |i_CTRL-X_CTRL-o|
-- |tagfunc| is set to |vim.lsp.tagfunc|. This enables features like
+- 'omnifunc' is set to |vim.lsp.omnifunc()|. This allows to trigger completion
+  using |i_CTRL-X_CTRL-O|
+- 'tagfunc' is set to |vim.lsp.tagfunc()|. This enables features like
   go-to-definition, |:tjump|, and keymaps like |CTRL-]|, |CTRL-W_]|,
   |CTRL-W_}| to utilize the language server.
-- |formatexpr| is set to |vim.lsp.formatexpr| if both |formatprg| and
-  |formatexpr| are empty. This allows to format lines via |gq| if the language
+- 'formatexpr' is set to |vim.lsp.formatexpr()| if both 'formatprg' and
+  'formatexpr' are empty. This allows to format lines via |gq| if the language
   server supports it.
 
 To use other LSP features like hover, rename, etc. you can setup some
 additional keymaps. It's recommended to setup them in a |LspAttach| autocmd to
 ensure they're only active if there is a LSP client running. An example:
->
+>lua
     vim.api.nvim_create_autocmd('LspAttach', {
       callback = function(args)
         vim.keymap.set('n', 'K', vim.lsp.buf.hover, { buffer = args.buf })
@@ -86,7 +86,7 @@ The most used functions are:
 Not all language servers provide the same capabilities. To ensure you only set
 keymaps if the language server supports a feature, you can guard the keymap
 calls behind capability checks:
->
+>lua
     vim.api.nvim_create_autocmd('LspAttach', {
       callback = function(args)
         local client = vim.lsp.get_client_by_id(args.data.client_id)
@@ -100,7 +100,7 @@ calls behind capability checks:
 To learn what capabilities are available you can run the following command in
 a buffer with a started LSP client:
 
->
+>vim
     :lua =vim.lsp.get_active_clients()[1].server_capabilities
 <
 
@@ -110,14 +110,14 @@ Full list of features provided by default can be found in |lsp-buf|.
 FAQ                                                     *lsp-faq*
 
 - Q: How to force-reload LSP?
-  A: Stop all clients, then reload the buffer. >
+  A: Stop all clients, then reload the buffer. >vim
 
      :lua vim.lsp.stop_client(vim.lsp.get_active_clients())
      :edit
 
 - Q: Why isn't completion working?
   A: In the buffer where you want to use LSP, check that 'omnifunc' is set to
-     "v:lua.vim.lsp.omnifunc": >
+     "v:lua.vim.lsp.omnifunc": >vim
 
      :verbose set omnifunc?
 
@@ -126,13 +126,14 @@ FAQ                                                     *lsp-faq*
      "after/ftplugin/python.vim".
 
 - Q: How do I run a request synchronously (e.g. for formatting on file save)?
-  A: Use the `_sync` variant of the function provided by |lsp-buf|, if it
-     exists.
+  A: Check if the function has an `async` parameter and set the value to
+  false.
 
-     E.g. code formatting: >
+     E.g. code formatting: >vim
 
      " Auto-format *.rs (rust) files prior to saving them
-     autocmd BufWritePre *.rs lua vim.lsp.buf.formatting_sync(nil, 1000)
+     " (async = false is the default for format)
+     autocmd BufWritePre *.rs lua vim.lsp.buf.format({ async = false })
 
 <
                                                            *lsp-vs-treesitter*
@@ -161,7 +162,7 @@ to the given buffer. |lsp-buf|
 
 LSP request/response handlers are implemented as Lua functions (see
 |lsp-handler|). The |vim.lsp.handlers| table defines default handlers used
-when creating a new client. Keys are LSP method names: >
+when creating a new client. Keys are LSP method names: >vim
 
     :lua print(vim.inspect(vim.tbl_keys(vim.lsp.handlers)))
 <
@@ -189,6 +190,7 @@ specification. These LSP requests/notifications are defined by default:
     textDocument/typeDefinition*
     window/logMessage
     window/showMessage
+    window/showDocument
     window/showMessageRequest
     workspace/applyEdit
     workspace/symbol
@@ -244,7 +246,7 @@ For |lsp-request|, each |lsp-handler| has this signature: >
         Where `err` must be shaped like an RPC error:
             `{ code, message, data? }`
 
-        You can use |vim.lsp.rpc_response_error()| to create this object.
+        You can use |vim.lsp.rpc.rpc_response_error()| to create this object.
 
 For |lsp-notification|, each |lsp-handler| has this signature: >
 
@@ -289,7 +291,7 @@ To configure the behavior of a builtin |lsp-handler|, the convenient method
 
   To configure the behavior of |vim.lsp.diagnostic.on_publish_diagnostics()|,
   consider the following example, where a new |lsp-handler| is created using
-  |vim.lsp.with()| that no longer generates signs for the diagnostics: >
+  |vim.lsp.with()| that no longer generates signs for the diagnostics: >lua
 
     vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with(
       vim.lsp.diagnostic.on_publish_diagnostics, {
@@ -299,7 +301,7 @@ To configure the behavior of a builtin |lsp-handler|, the convenient method
     )
 <
   To enable signs, use |vim.lsp.with()| again to create and assign a new
-  |lsp-handler| to |vim.lsp.handlers| for the associated method: >
+  |lsp-handler| to |vim.lsp.handlers| for the associated method: >lua
 
     vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with(
       vim.lsp.diagnostic.on_publish_diagnostics, {
@@ -309,7 +311,7 @@ To configure the behavior of a builtin |lsp-handler|, the convenient method
     )
 <
   To configure a handler on a per-server basis, you can use the {handlers} key
-  for |vim.lsp.start_client()| >
+  for |vim.lsp.start_client()| >lua
 
     vim.lsp.start_client {
       ..., -- Other configuration omitted.
@@ -323,7 +325,8 @@ To configure the behavior of a builtin |lsp-handler|, the convenient method
       },
     }
 <
-  or if using 'nvim-lspconfig', you can use the {handlers} key of `setup()`: >
+  or if using "nvim-lspconfig", you can use the {handlers} key of `setup()`:
+  >lua
 
     require('lspconfig').rust_analyzer.setup {
       handlers = {
@@ -337,8 +340,8 @@ To configure the behavior of a builtin |lsp-handler|, the convenient method
     }
 <
   Some handlers do not have an explicitly named handler function (such as
-  |on_publish_diagnostics()|). To override these, first create a reference
-  to the existing handler: >
+  ||vim.lsp.diagnostic.on_publish_diagnostics()|). To override these, first
+  create a reference to the existing handler: >lua
 
     local on_references = vim.lsp.handlers["textDocument/references"]
     vim.lsp.handlers["textDocument/references"] = vim.lsp.with(
@@ -355,14 +358,14 @@ Handlers can be set by:
     vim.lsp.handlers is a global table that contains the default mapping of
     |lsp-method| names to |lsp-handlers|.
 
-    To override the handler for the `"textDocument/definition"` method: >
+    To override the handler for the `"textDocument/definition"` method: >lua
 
     vim.lsp.handlers["textDocument/definition"] = my_custom_default_definition
 <
-- The {handlers} parameter for |vim.lsp.start_client|.
+- The {handlers} parameter for |vim.lsp.start_client()|.
     This will set the |lsp-handler| as the default handler for this server.
 
-    For example: >
+    For example: >lua
 
     vim.lsp.start_client {
       ..., -- Other configuration omitted.
@@ -374,7 +377,7 @@ Handlers can be set by:
 - The {handler} parameter for |vim.lsp.buf_request()|.
     This will set the |lsp-handler| ONLY for the current request.
 
-    For example: >
+    For example: >lua
 
     vim.lsp.buf_request(
       0,
@@ -401,7 +404,7 @@ and helper functions for creating protocol-related objects.
 https://github.com/microsoft/language-server-protocol/raw/gh-pages/_specifications/specification-3-14.md
 
 For example `vim.lsp.protocol.ErrorCodes` allows reverse lookup by number or
-name: >
+name: >lua
 
     vim.lsp.protocol.TextDocumentSyncKind.Full == 1
     vim.lsp.protocol.TextDocumentSyncKind[1] == "Full"
@@ -424,7 +427,7 @@ For the format of the notification message, see:
  - `context` table|nil. `ctx` from |lsp-handler|
 
 This table can be used with vim.fn.setqflist or vim.fn.setloclist. E.g.:
->
+>lua
     local function on_list(options)
       vim.fn.setqflist({}, ' ', options)
       vim.api.nvim_command('cfirst')
@@ -434,7 +437,7 @@ This table can be used with vim.fn.setqflist or vim.fn.setloclist. E.g.:
     vim.lsp.buf.references(nil, {on_list=on_list})
 <
 If you prefer loclist do something like this:
->
+>lua
     local function on_list(options)
       vim.fn.setloclist(0, {}, ' ', options)
       vim.api.nvim_command('lopen')
@@ -468,7 +471,7 @@ LspCodeLens
     |nvim_buf_set_extmark()|.
 
 LspCodeLensSeparator                                 *hl-LspCodeLensSeparator*
-    Used to color the separator between two or more code lens.
+    Used to color the separator between two or more code lenses.
 
                                                      *lsp-highlight-signature*
 
@@ -485,7 +488,7 @@ EVENTS                                                            *lsp-events*
                                                                    *LspAttach*
 After an LSP client attaches to a buffer. The |autocmd-pattern| is the
 name of the buffer. When used from Lua, the client ID is passed to the
-callback in the "data" table. Example: >
+callback in the "data" table. Example: >lua
 
     vim.api.nvim_create_autocmd("LspAttach", {
       callback = function(args)
@@ -503,7 +506,7 @@ callback in the "data" table. Example: >
                                                                    *LspDetach*
 Just before an LSP client detaches from a buffer. The |autocmd-pattern| is the
 name of the buffer. When used from Lua, the client ID is passed to the
-callback in the "data" table. Example: >
+callback in the "data" table. Example: >lua
 
     vim.api.nvim_create_autocmd("LspDetach", {
       callback = function(args)
@@ -513,7 +516,7 @@ callback in the "data" table. Example: >
       end,
     })
 <
-In addition, the following |User| |autocommands| are provided:
+Also the following |User| |autocommand|s are provided:
 
 LspProgressUpdate                                          *LspProgressUpdate*
     Upon receipt of a progress notification from the server. See
@@ -523,7 +526,7 @@ LspRequest                                                        *LspRequest*
     After a change to the active set of pending LSP requests. See {requests}
     in |vim.lsp.client|.
 
-Example: >
+Example: >vim
     autocmd User LspProgressUpdate redrawstatus
     autocmd User LspRequest redrawstatus
 <
@@ -538,8 +541,8 @@ buf_attach_client({bufnr}, {client_id})          *vim.lsp.buf_attach_client()*
     Without calling this, the server won't be notified of changes to a buffer.
 
     Parameters: ~
-        {bufnr}      (number) Buffer handle, or 0 for current
-        {client_id}  (number) Client id
+      • {bufnr}      (number) Buffer handle, or 0 for current
+      • {client_id}  (number) Client id
 
 buf_detach_client({bufnr}, {client_id})          *vim.lsp.buf_detach_client()*
     Detaches client from the specified buffer. Note: While the server is
@@ -547,23 +550,23 @@ buf_detach_client({bufnr}, {client_id})          *vim.lsp.buf_detach_client()*
     send notifications should it ignore this notification.
 
     Parameters: ~
-        {bufnr}      (number) Buffer handle, or 0 for current
-        {client_id}  (number) Client id
+      • {bufnr}      (number) Buffer handle, or 0 for current
+      • {client_id}  (number) Client id
 
 buf_is_attached({bufnr}, {client_id})              *vim.lsp.buf_is_attached()*
     Checks if a buffer is attached for a particular client.
 
     Parameters: ~
-        {bufnr}      (number) Buffer handle, or 0 for current
-        {client_id}  (number) the client id
+      • {bufnr}      (number) Buffer handle, or 0 for current
+      • {client_id}  (number) the client id
 
 buf_notify({bufnr}, {method}, {params})                 *vim.lsp.buf_notify()*
     Send a notification to a server
 
     Parameters: ~
-        {bufnr}   [number] (optional): The number of the buffer
-        {method}  [string]: Name of the request method
-        {params}  [string]: Arguments to send to the server
+      • {bufnr}   (number|nil) The number of the buffer
+      • {method}  (string) Name of the request method
+      • {params}  (any) Arguments to send to the server
 
     Return: ~
         true if any client returns true; false otherwise
@@ -575,10 +578,10 @@ buf_request_all({bufnr}, {method}, {params}, {callback})
     |vim.lsp.buf_request()| but the return result and callback are different.
 
     Parameters: ~
-        {bufnr}     (number) Buffer handle, or 0 for current.
-        {method}    (string) LSP method name
-        {params}    (optional, table) Parameters to send to the server
-        {callback}  (function) The callback to call when all requests are
+      • {bufnr}     (number) Buffer handle, or 0 for current.
+      • {method}    (string) LSP method name
+      • {params}    (table|nil) Parameters to send to the server
+      • {callback}  (function) The callback to call when all requests are
                     finished.
 
     Return: ~
@@ -594,11 +597,11 @@ buf_request_sync({bufnr}, {method}, {params}, {timeout_ms})
     result is different. Wait maximum of {timeout_ms} (default 1000) ms.
 
     Parameters: ~
-        {bufnr}       (number) Buffer handle, or 0 for current.
-        {method}      (string) LSP method name
-        {params}      (optional, table) Parameters to send to the server
-        {timeout_ms}  (optional, number, default=1000) Maximum time in
-                      milliseconds to wait for a result.
+      • {bufnr}       (number) Buffer handle, or 0 for current.
+      • {method}      (string) LSP method name
+      • {params}      (table|nil) Parameters to send to the server
+      • {timeout_ms}  (number|nil) Maximum time in milliseconds to wait for a
+                      result. Defaults to 1000
 
     Return: ~
         Map of client_id:request_result. On timeout, cancel or error, returns
@@ -665,7 +668,7 @@ client_is_stopped({client_id})                   *vim.lsp.client_is_stopped()*
     Checks whether a client is stopped.
 
     Parameters: ~
-        {client_id}  (Number)
+      • {client_id}  (number)
 
     Return: ~
         true if client is stopped, false otherwise.
@@ -675,10 +678,10 @@ for_each_buffer_client({bufnr}, {fn})
     Invokes a function for each LSP client attached to a buffer.
 
     Parameters: ~
-        {bufnr}  (number) Buffer number
-        {fn}     (function) Function to run on each client attached to buffer
+      • {bufnr}  (number) Buffer number
+      • {fn}     (function) Function to run on each client attached to buffer
                  {bufnr}. The function takes the client, client ID, and buffer
-                 number as arguments. Example: >
+                 number as arguments. Example: >lua
 
                    vim.lsp.for_each_buffer_client(0, function(client, client_id, bufnr)
                      print(vim.inspect(client))
@@ -695,7 +698,7 @@ formatexpr({opts})                                      *vim.lsp.formatexpr()*
     'v:lua.vim.lsp.formatexpr(#{timeout_ms:250})')`.
 
     Parameters: ~
-        {opts}  (table) options for customizing the formatting expression
+      • {opts}  (table) options for customizing the formatting expression
                 which takes the following optional keys:
                 • timeout_ms (default 500ms). The timeout period for the
                   formatting request.
@@ -704,7 +707,7 @@ get_active_clients({filter})                    *vim.lsp.get_active_clients()*
     Get active clients.
 
     Parameters: ~
-        {filter}  (table|nil) A table with key-value pairs used to filter the
+      • {filter}  (table|nil) A table with key-value pairs used to filter the
                   returned clients. The available keys are:
                   • id (number): Only return clients with the given id
                   • bufnr (number): Only return clients attached to this
@@ -719,17 +722,17 @@ get_buffers_by_client_id({client_id})
     Returns list of buffers attached to client_id.
 
     Parameters: ~
-        {client_id}  (number) client id
+      • {client_id}  (number) client id
 
     Return: ~
-        list of buffer ids
+        (list) of buffer ids
 
 get_client_by_id({client_id})                     *vim.lsp.get_client_by_id()*
     Gets a client by id, or nil if the id is invalid. The returned client may
     not yet be fully initialized.
 
     Parameters: ~
-        {client_id}  (number) client id
+      • {client_id}  (number) client id
 
     Return: ~
         |vim.lsp.client| object, or nil
@@ -744,8 +747,8 @@ omnifunc({findstart}, {base})                             *vim.lsp.omnifunc()*
     Implements 'omnifunc' compatible LSP completion.
 
     Parameters: ~
-        {findstart}  0 or 1, decides behavior
-        {base}       If findstart=0, text to match against
+      • {findstart}  (number) 0 or 1, decides behavior
+      • {base}       (number) findstart=0, text to match against
 
     Return: ~
         (number) Decided by {findstart}:
@@ -767,7 +770,7 @@ set_log_level({level})                               *vim.lsp.set_log_level()*
     Use `lsp.log_levels` for reverse lookup.
 
     Parameters: ~
-        {level}  [number|string] the case insensitive level name or number
+      • {level}  (number|string) the case insensitive level name or number
 
     See also: ~
         |vim.lsp.log_levels|
@@ -777,173 +780,170 @@ start({config}, {opts})                                      *vim.lsp.start()*
     running client if one is found matching `name` and `root_dir`. Attaches
     the current buffer to the client.
 
-    Example:
->
+    Example: >lua
 
-    vim.lsp.start({
-       name = 'my-server-name',
-       cmd = {'name-of-language-server-executable'},
-       root_dir = vim.fs.dirname(vim.fs.find({'pyproject.toml', 'setup.py'}, { upward = true })[1]),
-    })
+     vim.lsp.start({
+        name = 'my-server-name',
+        cmd = {'name-of-language-server-executable'},
+        root_dir = vim.fs.dirname(vim.fs.find({'pyproject.toml', 'setup.py'}, { upward = true })[1]),
+     })
 <
 
-    See |lsp.start_client| for all available options. The most important are:
-
-    `name` is an arbitrary name for the LSP client. It should be unique per
-    language server.
-
-    `cmd` the command as list - used to start the language server. The command must
-    be present in the `$PATH` environment variable or an absolute path to the executable. Shell
-    constructs like `~` are NOT expanded.
-
-    `root_dir` path to the project root. By default this is used to decide if
-    an existing client should be re-used. The example above uses |vim.fs.find|
-    and |vim.fs.dirname| to detect the root by traversing the file system
-    upwards starting from the current directory until either a
-    `pyproject.toml` or `setup.py` file is found.
-
-    `workspace_folders` a list of { uri:string, name: string } tables. The
-    project root folders used by the language server. If `nil` the property is
-    derived from the `root_dir` for convenience.
+    See |vim.lsp.start_client()| for all available options. The most important
+    are:
+
+    • `name` arbitrary name for the LSP client. Should be unique per language
+      server.
+    • `cmd` command (in list form) used to start the language server. Must be
+      absolute, or found on `$PATH`. Shell constructs like `~` are not
+      expanded.
+    • `root_dir` path to the project root. By default this is used to decide
+      if an existing client should be re-used. The example above uses
+      |vim.fs.find()| and |vim.fs.dirname()| to detect the root by traversing
+      the file system upwards starting from the current directory until either
+      a `pyproject.toml` or `setup.py` file is found.
+    • `workspace_folders` list of `{ uri:string, name: string }` tables
+      specifying the project root folders used by the language server. If
+      `nil` the property is derived from `root_dir` for convenience.
 
     Language servers use this information to discover metadata like the
     dependencies of your project and they tend to index the contents within
     the project folder.
 
     To ensure a language server is only started for languages it can handle,
-    make sure to call |vim.lsp.start| within a |FileType| autocmd. Either use
-    |:au|, |nvim_create_autocmd()| or put the call in a
+    make sure to call |vim.lsp.start()| within a |FileType| autocmd. Either
+    use |:au|, |nvim_create_autocmd()| or put the call in a
     `ftplugin/<filetype_name>.lua` (See |ftplugin-name|)
 
     Parameters: ~
-        {config}  (table) Same configuration as documented in
-                  |lsp.start_client()|
-        {opts}    nil|table Optional keyword arguments:
+      • {config}  (table) Same configuration as documented in
+                  |vim.lsp.start_client()|
+      • {opts}    nil|table Optional keyword arguments:
                   • reuse_client (fun(client: client, config: table): boolean)
                     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.
+                  • bufnr (number) Buffer handle to attach to if starting or
+                    re-using a client (0 for current).
 
     Return: ~
-        (number) client_id
+        (number|nil) client_id
 
 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}                (required, string or list treated like
-                             |jobstart()|) Base command that initiates the LSP
-                             client.
-        {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
@@ -953,19 +953,18 @@ start_client({config})                                *vim.lsp.start_client()*
 stop_client({client_id}, {force})                      *vim.lsp.stop_client()*
     Stops a client(s).
 
-    You can also use the `stop()` function on a |vim.lsp.client| object. To
-    stop all clients:
->
+    You can also use the `stop()` function on a |vim.lsp.client| object. To stop all clients: >lua
 
-    vim.lsp.stop_client(vim.lsp.get_active_clients())
+     vim.lsp.stop_client(vim.lsp.get_active_clients())
 <
 
     By default asks the server to shutdown, unless stop was requested already
     for this client, then force-shutdown is attempted.
 
     Parameters: ~
-        {client_id}  client id or |vim.lsp.client| object, or list thereof
-        {force}      (boolean) (optional) shutdown forcefully
+      • {client_id}  number|table id or |vim.lsp.client| object, or list
+                     thereof
+      • {force}      (boolean|nil) shutdown forcefully
 
 tagfunc({...})                                             *vim.lsp.tagfunc()*
     Provides an interface between the built-in client and 'tagfunc'.
@@ -976,8 +975,8 @@ tagfunc({...})                                             *vim.lsp.tagfunc()*
     LSP servers, falls back to using built-in tags.
 
     Parameters: ~
-        {pattern}  Pattern used to find a workspace symbol
-        {flags}    See |tag-function|
+      • {pattern}  (string) Pattern used to find a workspace symbol
+      • {flags}    (string) See |tag-function|
 
     Return: ~
         A list of matching tags
@@ -986,8 +985,8 @@ with({handler}, {override_config})                            *vim.lsp.with()*
     Function to manage overriding defaults for LSP handlers.
 
     Parameters: ~
-        {handler}          (function) See |lsp-handler|
-        {override_config}  (table) Table containing the keys