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

1 files changed, 742 insertions, 589 deletions

diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 215515a2d9..5e97628f42 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -24,57 +24,62 @@ QUICKSTART                                              *lsp-quickstart*
 Nvim provides an LSP client, but the servers are provided by third parties.
 Follow these steps to get LSP features:
 
-  1. Install language servers using your package manager or by
-     following the upstream installation instruction.
+1. Install language servers using your package manager or by following the
+   upstream installation instruction. You can find language servers here:
+   https://microsoft.github.io/language-server-protocol/implementors/servers/
 
-     A list of language servers is available at:
+2. Configure the LSP client per language server. See |vim.lsp.start()| or use
+   this minimal example as a guide: >lua
 
-     https://microsoft.github.io/language-server-protocol/implementors/servers/
-
-  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.
+3. Check that the server attached to the buffer: >
+    :lua =vim.lsp.get_clients()
 
-  3. Configure keymaps and autocmds to utilize LSP features.
-     See |lsp-config|.
+4. Configure keymaps and autocmds to use 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
-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|
+                                                        *lsp-defaults*
+When the LSP client starts it enables diagnostics |vim.diagnostic| (see
+|vim.diagnostic.config()| to customize). It also sets various default options,
+listed below, if (1) the language server supports the functionality and (2)
+the options are empty or were set by the builtin runtime (ftplugin) files. The
+options are not restored when the LSP client is stopped or detached.
+
+- 'omnifunc' is set to |vim.lsp.omnifunc()|, use |i_CTRL-X_CTRL-O| to trigger
+  completion.
 - '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
-  server supports it.
+- 'formatexpr' is set to |vim.lsp.formatexpr()|, so you can format lines via
+  |gq| if the language server supports it.
+  - To opt out of this use |gw| instead of gq, or set 'formatexpr' on LspAttach.
+- |K| is mapped to |vim.lsp.buf.hover()| unless |'keywordprg'| is customized or
+  a custom keymap for `K` exists.
+
+                                                        *lsp-defaults-disable*
+To override the above defaults, set or unset the options on |LspAttach|: >lua
+    vim.api.nvim_create_autocmd('LspAttach', {
+      callback = function(ev)
+        vim.bo[ev.buf].formatexpr = nil
+        vim.bo[ev.buf].omnifunc = nil
+        vim.keymap.del("n", "K", { buffer = ev.buf })
+      end,
+    })
 
-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
+To use other LSP features like hover, rename, etc. you can set other keymaps
+on |LspAttach|. Example: >lua
     vim.api.nvim_create_autocmd('LspAttach', {
       callback = function(args)
         vim.keymap.set('n', 'K', vim.lsp.buf.hover, { buffer = args.buf })
       end,
     })
 
-<
-The most used functions are:
+The most common functions are:
 
 - |vim.lsp.buf.hover()|
 - |vim.lsp.buf.format()|
@@ -98,11 +103,9 @@ calls behind capability checks:
 <
 
 To learn what capabilities are available you can run the following command in
-a buffer with a started LSP client:
+a buffer with a started LSP client: >vim
 
->vim
-    :lua =vim.lsp.get_active_clients()[1].server_capabilities
-<
+    :lua =vim.lsp.get_clients()[1].server_capabilities
 
 Full list of features provided by default can be found in |lsp-buf|.
 
@@ -110,35 +113,28 @@ 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. >vim
-
-     :lua vim.lsp.stop_client(vim.lsp.get_active_clients())
+- A: Stop all clients, then reload the buffer. >vim
+     :lua vim.lsp.stop_client(vim.lsp.get_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": >vim
-
-     :verbose set omnifunc?
-
-<     Some other plugin may be overriding the option. To avoid that, you could
-     set the option in an |after-directory| ftplugin, e.g.
-     "after/ftplugin/python.vim".
+- A: In the buffer where you want to use LSP, check that 'omnifunc' is set to
+     "v:lua.vim.lsp.omnifunc": `:verbose set omnifunc?`
+     - Some other plugin may be overriding the option. To avoid that you could
+       set the option in an |after-directory| ftplugin, e.g.
+       "after/ftplugin/python.vim".
 
 - Q: How do I run a request synchronously (e.g. for formatting on file save)?
-  A: Check if the function has an `async` parameter and set the value to
-  false.
-
-     E.g. code formatting: >vim
+- A: Check if the function has an `async` parameter and set the value to
+  false. E.g. code formatting: >vim
 
      " Auto-format *.rs (rust) files prior to saving them
      " (async = false is the default for format)
      autocmd BufWritePre *.rs lua vim.lsp.buf.format({ async = false })
-
 <
                                                            *lsp-vs-treesitter*
 - Q: How do LSP and Treesitter compare?
-  A: LSP requires a client and language server. The language server uses
+- A: LSP requires a client and language server. The language server uses
      semantic analysis to understand code at a project level. This provides
      language servers with the ability to rename across files, find
      definitions in external libraries and more.
@@ -161,128 +157,85 @@ The `vim.lsp.buf_…` functions perform operations for all LSP clients attached
 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: >vim
-
-    :lua print(vim.inspect(vim.tbl_keys(vim.lsp.handlers)))
-<
+|lsp-handler|).
                                                                   *lsp-method*
 
-Methods are the names of requests and notifications as defined by the LSP
-specification. These LSP requests/notifications are defined by default:
-
-    callHierarchy/incomingCalls
-    callHierarchy/outgoingCalls
-    textDocument/codeAction
-    textDocument/completion
-    textDocument/declaration*
-    textDocument/definition
-    textDocument/documentHighlight
-    textDocument/documentSymbol
-    textDocument/formatting
-    textDocument/hover
-    textDocument/implementation*
-    textDocument/publishDiagnostics
-    textDocument/rangeFormatting
-    textDocument/references
-    textDocument/rename
-    textDocument/signatureHelp
-    textDocument/typeDefinition*
-    window/logMessage
-    window/showMessage
-    window/showDocument
-    window/showMessageRequest
-    workspace/applyEdit
-    workspace/symbol
-
-* NOTE: These are sometimes not implemented by servers.
-
-                                                                 *lsp-handler*
+Requests and notifications defined by the LSP specification are referred to as
+"LSP methods". The Nvim LSP client provides default handlers in the global
+|vim.lsp.handlers| table, you can list them with this command: >vim
 
-lsp-handlers are functions with special signatures that are designed to handle
-responses and notifications from LSP servers.
-
-For |lsp-request|, each |lsp-handler| has this signature: >
-
-  function(err, result, ctx, config)
+    :lua vim.print(vim.tbl_keys(vim.lsp.handlers))
 <
-    Parameters: ~
-        {err}       (table|nil)
-                        When the language server is unable to complete a
-                        request, a table with information about the error is
-                        sent. Otherwise, it is `nil`. See |lsp-response|.
-        {result}    (Result | Params | nil)
-                        When the language server is able to successfully
-                        complete a request, this contains the `result` key of
-                        the response. See |lsp-response|.
-        {ctx}       (table)
-                        Context describes additional calling state associated
-                        with the handler. It consists of the following key,
-                        value pairs:
-
-                        {method}    (string)
-                                    The |lsp-method| name.
-                        {client_id} (number)
-                                    The ID of the |vim.lsp.client|.
-                        {bufnr}     (Buffer)
-                                    Buffer handle, or 0 for current.
-                        {params}    (table|nil)
-                                    The parameters used in the original
-                                    request which resulted in this handler
-                                    call.
-        {config}    (table)
-                        Configuration for the handler.
-
-                        Each handler can define its own configuration table
-                        that allows users to customize the behavior of a
-                        particular handler.
-
-                        To configure a particular |lsp-handler|, see:
-                            |lsp-handler-configuration|
-
-
-    Returns: ~
-        The |lsp-handler| can respond by returning two values: `result, err`
-        Where `err` must be shaped like an RPC error:
-            `{ code, message, data? }`
+They are also listed below. Note that handlers depend on server support: they
+won't run if your server doesn't support them.
+
+- callHierarchy/incomingCalls
+- callHierarchy/outgoingCalls
+- textDocument/codeAction
+- textDocument/completion
+- textDocument/declaration*
+- textDocument/definition
+- textDocument/diagnostic
+- textDocument/documentHighlight
+- textDocument/documentSymbol
+- textDocument/formatting
+- textDocument/hover
+- textDocument/implementation*
+- textDocument/inlayHint
+- textDocument/publishDiagnostics
+- textDocument/rangeFormatting
+- textDocument/references
+- textDocument/rename
+- textDocument/semanticTokens/full
+- textDocument/semanticTokens/full/delta
+- textDocument/signatureHelp
+- textDocument/typeDefinition*
+- window/logMessage
+- window/showMessage
+- window/showDocument
+- window/showMessageRequest
+- workspace/applyEdit
+- workspace/configuration
+- workspace/executeCommand
+- workspace/inlayHint/refresh
+- workspace/symbol
+- workspace/workspaceFolders
 
-        You can use |vim.lsp.rpc.rpc_response_error()| to create this object.
+                                                                 *lsp-handler*
+LSP handlers are functions that handle |lsp-response|s to requests made by Nvim
+to the server. (Notifications, as opposed to requests, are fire-and-forget:
+there is no response, so they can't be handled. |lsp-notification|)
 
-For |lsp-notification|, each |lsp-handler| has this signature: >
+Each response handler has this signature: >
 
-  function(err, result, ctx, config)
+    function(err, result, ctx, config)
 <
     Parameters: ~
-        {err}       (nil)
-                        This is always `nil`.
-                        See |lsp-notification|
-        {result}    (Result)
-                        This contains the `params` key of the notification.
-                        See |lsp-notification|
-        {ctx}       (table)
-                        Context describes additional calling state associated
-                        with the handler. It consists of the following key,
-                        value pairs:
-
-                        {method}    (string)
-                                        The |lsp-method| name.
-                        {client_id} (number)
-                                        The ID of the |vim.lsp.client|.
-        {config}    (table)
-                        Configuration for the handler.
-
-                        Each handler can define its own configuration table
-                        that allows users to customize the behavior of a
-                        particular handler.
-
-                        For an example, see:
-                            |vim.lsp.diagnostic.on_publish_diagnostics()|
-
-                        To configure a particular |lsp-handler|, see:
-                            |lsp-handler-configuration|
+        - {err}     (table|nil) Error info dict, or `nil` if the request
+                    completed.
+        - {result}  (Result | Params | nil) `result` key of the |lsp-response| or
+                    `nil` if the request failed.
+        - {ctx}     (table) Table of calling state associated with the
+                    handler, with these keys:
+                    - {method}  (string) |lsp-method| name.
+                    - {client_id} (number) |vim.lsp.client| identifier.
+                    - {bufnr}   (Buffer) Buffer handle.
+                    - {params}  (table|nil) Request parameters table.
+                    - {version} (number) Document version at time of
+                                request. Handlers can compare this to the
+                                current document version to check if the
+                                response is "stale". See also |b:changedtick|.
+        - {config}  (table) Handler-defined configuration table, which allows
+                    users to customize handler behavior.
+                    For an example, see:
+                        |vim.lsp.diagnostic.on_publish_diagnostics()|
+                    To configure a particular |lsp-handler|, see:
+                        |lsp-handler-configuration|
 
     Returns: ~
-        The |lsp-handler|'s return value will be ignored.
+        Two values `result, err` where `err` is shaped like an RPC error: >
+            { code, message, data? }
+<        You can use |vim.lsp.rpc.rpc_response_error()| to create this object.
 
                                                    *lsp-handler-configuration*
 
@@ -355,42 +308,37 @@ To configure the behavior of a builtin |lsp-handler|, the convenient method
 Handlers can be set by:
 
 - Setting a field in vim.lsp.handlers.                      *vim.lsp.handlers*
-    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: >lua
+  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: >lua
 
     vim.lsp.handlers["textDocument/definition"] = my_custom_default_definition
 <
-- The {handlers} parameter for |vim.lsp.start_client()|.
-    This will set the |lsp-handler| as the default handler for this server.
+- The {handlers} parameter of |vim.lsp.start()|. This sets the default
+  |lsp-handler| for the server being started. Example: >lua
 
-    For example: >lua
-
-    vim.lsp.start_client {
+    vim.lsp.start {
       ..., -- Other configuration omitted.
       handlers = {
         ["textDocument/definition"] = my_custom_server_definition
       },
     }
 
-- The {handler} parameter for |vim.lsp.buf_request()|.
-    This will set the |lsp-handler| ONLY for the current request.
+- The {handler} parameter of |vim.lsp.buf_request_all()|. This sets
+  the |lsp-handler| ONLY for the given request(s). Example: >lua
 
-    For example: >lua
-
-    vim.lsp.buf_request(
+    vim.lsp.buf_request_all(
       0,
       "textDocument/definition",
-      definition_params,
-      my_request_custom_definition
+      my_request_params,
+      my_handler
     )
 <
 In summary, the |lsp-handler| will be chosen based on the current |lsp-method|
 in the following order:
 
-1. Handler passed to |vim.lsp.buf_request()|, if any.
-2. Handler defined in |vim.lsp.start_client()|, if any.
+1. Handler passed to |vim.lsp.buf_request_all()|, if any.
+2. Handler defined in |vim.lsp.start()|, if any.
 3. Handler defined in |vim.lsp.handlers|, if any.
 
                                                             *vim.lsp.log_levels*
@@ -411,12 +359,12 @@ name: >lua
 <
 
                                                                 *lsp-response*
-For the format of the response message, see:
-    https://microsoft.github.io/language-server-protocol/specifications/specification-current/#responseMessage
+LSP response shape:
+https://microsoft.github.io/language-server-protocol/specifications/specification-current/#responseMessage
 
                                                                 *lsp-notification*
-For the format of the notification message, see:
-    https://microsoft.github.io/language-server-protocol/specifications/specification-current/#notificationMessage
+LSP notification shape:
+https://microsoft.github.io/language-server-protocol/specifications/specification-current/#notificationMessage
 
                                                                 *lsp-on-list-handler*
 
@@ -459,6 +407,8 @@ LspReferenceText          used for highlighting "text" references
 LspReferenceRead          used for highlighting "read" references
                                                           *hl-LspReferenceWrite*
 LspReferenceWrite         used for highlighting "write" references
+                                                          *hl-LspInlayHint*
+LspInlayHint              used for highlighting inlay hints
 
 
                                                       *lsp-highlight-codelens*
@@ -482,13 +432,78 @@ LspSignatureActiveParameter
     Used to highlight the active parameter in the signature help. See
     |vim.lsp.handlers.signature_help()|.
 
+------------------------------------------------------------------------------
+LSP SEMANTIC HIGHLIGHTS                               *lsp-semantic-highlight*
+
+When available, the LSP client highlights code using |lsp-semantic_tokens|,
+which are another way that LSP servers can provide information about source
+code.  Note that this is in addition to treesitter syntax highlighting;
+semantic highlighting does not replace syntax highlighting.
+
+The server will typically provide one token per identifier in the source code.
+The token will have a `type` such as "function" or "variable", and 0 or more
+`modifier`s such as "readonly" or "deprecated." The standard types and
+modifiers are described here:
+https://microsoft.github.io/language-server-protocol/specification/#textDocument_semanticTokens
+LSP servers may also use off-spec types and modifiers.
+
+The LSP client adds one or more highlights for each token. The highlight
+groups are derived from the token's type and modifiers:
+  • `@lsp.type.<type>.<ft>` for the type
+  • `@lsp.mod.<mod>.<ft>` for each modifier
+  • `@lsp.typemod.<type>.<mod>.<ft>` for each modifier
+Use |:Inspect| to view the highlights for a specific token. Use |:hi| or
+|nvim_set_hl()| to change the appearance of semantic highlights: >vim
+
+    hi @lsp.type.function guifg=Yellow        " function names are yellow
+    hi @lsp.type.variable.lua guifg=Green     " variables in lua are green
+    hi @lsp.mod.deprecated gui=strikethrough  " deprecated is crossed out
+    hi @lsp.typemod.function.async guifg=Blue " async functions are blue
+<
+The value |vim.highlight.priorities|`.semantic_tokens` is the priority of the
+`@lsp.type.*` highlights. The `@lsp.mod.*` and `@lsp.typemod.*` highlights
+have priorities one and two higher, respectively.
+
+You can disable semantic highlights by clearing the highlight groups: >lua
+
+    -- Hide semantic highlights for functions
+    vim.api.nvim_set_hl(0, '@lsp.type.function', {})
+
+    -- Hide all semantic highlights
+    for _, group in ipairs(vim.fn.getcompletion("@lsp", "highlight")) do
+      vim.api.nvim_set_hl(0, group, {})
+    end
+<
+You probably want these inside a |ColorScheme| autocommand.
+
+Use |LspTokenUpdate| and |vim.lsp.semantic_tokens.highlight_token()| for more
+complex highlighting.
+
+The following groups are linked by default to standard |group-name|s:
+>
+    @lsp.type.class         Structure
+    @lsp.type.decorator     Function
+    @lsp.type.enum          Structure
+    @lsp.type.enumMember    Constant
+    @lsp.type.function      Function
+    @lsp.type.interface     Structure
+    @lsp.type.macro         Macro
+    @lsp.type.method        Function
+    @lsp.type.namespace     Structure
+    @lsp.type.parameter     Identifier
+    @lsp.type.property      Identifier
+    @lsp.type.struct        Structure
+    @lsp.type.type          Type
+    @lsp.type.typeParameter TypeDef
+    @lsp.type.variable      Identifier
+<
 ==============================================================================
 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: >lua
+LspAttach                                                          *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: >lua
 
     vim.api.nvim_create_autocmd("LspAttach", {
       callback = function(args)
@@ -503,10 +518,11 @@ callback in the "data" table. Example: >lua
       end,
     })
 <
-                                                                   *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: >lua
+
+LspDetach                                                          *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: >lua
 
     vim.api.nvim_create_autocmd("LspDetach", {
       callback = function(args)
@@ -516,20 +532,105 @@ callback in the "data" table. Example: >lua
       end,
     })
 <
-Also the following |User| |autocommand|s are provided:
 
-LspProgressUpdate                                          *LspProgressUpdate*
-    Upon receipt of a progress notification from the server. See
-    |vim.lsp.util.get_progress_messages()|.
+LspNotify                                                          *LspNotify*
+    This event is triggered after each successful notification sent to an
+    LSP server.
+
+    When used from Lua, the client_id, LSP method, and parameters are sent
+    in the "data" table. Example: >lua
+
+    vim.api.nvim_create_autocmd('LspNotify', {
+      callback = function(args)
+        local bufnr = args.buf
+        local client_id = args.data.client_id
+        local method = args.data.method
+        local params = args.data.params
+
+        -- do something with the notification
+        if method == 'textDocument/...' then
+          update_buffer(bufnr)
+        end
+      end,
+    })
+<
+
+LspProgress                                                       *LspProgress*
+    Upon receipt of a progress notification from the server. Notifications can
+    be polled from a `progress` ring buffer of a |vim.lsp.client| or use
+    |vim.lsp.status()| to get an aggregate message
+
+    If the server sends a "work done progress", the `pattern` is set to `kind`
+    (one of `begin`, `report` or `end`).
+
+    When used from Lua, the event contains a `data` table with `client_id` and
+    `result` properties. `result` will contain the request params sent by the
+    server.
+
+    Example: >vim
+        autocmd LspProgress * redrawstatus
+<
 
 LspRequest                                                        *LspRequest*
-    After a change to the active set of pending LSP requests. See {requests}
-    in |vim.lsp.client|.
+    For each request sent to an LSP server, this event is triggered for
+    every change to the request's status. The status can be one of
+    `pending`, `complete`, or `cancel` and is sent as the {type} on the
+    "data" table passed to the callback function.
+
+    It triggers when the initial request is sent ({type} == `pending`) and
+    when the LSP server responds ({type} == `complete`). If a cancellation
+    is requested using `client.cancel_request(request_id)`, then this event
+    will trigger with {type} == `cancel`.
+
+    When used from Lua, the client ID, request ID, and request are sent in
+    the "data" table. See {requests} in |vim.lsp.client| for details on the
+    {request} value. If the request type is `complete`, the request will be
+    deleted from the client's pending requests table immediately after
+    calling the event's callbacks. Example: >lua
+
+    vim.api.nvim_create_autocmd('LspRequest', {
+      callback = function(args)
+        local bufnr = args.buf
+        local client_id = args.data.client_id
+        local request_id = args.data.request_id
+        local request = args.data.request
+        if request.type == 'pending' then
+          -- do something with pending requests
+          track_pending(client_id, bufnr, request_id, request)
+        elseif request.type == 'cancel' then
+          -- do something with pending cancel requests
+          track_canceling(client_id, bufnr, request_id, request)
+        elseif request.type == 'complete' then
+          -- do something with finished requests. this pending
+          -- request entry is about to be removed since it is complete
+          track_finish(client_id, bufnr, request_id, request)
+        end
+      end,
+    })
+<
+
+LspTokenUpdate                                                *LspTokenUpdate*
+    When a visible semantic token is sent or updated by the LSP server, or
+    when an existing token becomes visible for the first time. The
+    |autocmd-pattern| is the name of the buffer. When used from Lua, the
+    token and client ID are passed to the callback in the "data" table. The
+    token fields are documented in |vim.lsp.semantic_tokens.get_at_pos()|.
+    Example:
+    >lua
 
-Example: >vim
-    autocmd User LspProgressUpdate redrawstatus
-    autocmd User LspRequest redrawstatus
+    vim.api.nvim_create_autocmd('LspTokenUpdate', {
+      callback = function(args)
+        local token = args.data.token
+        if token.type == 'variable' and not token.modifiers.readonly then
+          vim.lsp.semantic_tokens.highlight_token(
+            token, args.buf, args.data.client_id, 'MyMutableVariableHighlight'
+          )
+        end
+      end,
+    })
 <
+    Note: doing anything other than calling
+    |vim.lsp.semantic_tokens.highlight_token()| is considered experimental.
 
 ==============================================================================
 Lua module: vim.lsp                                                 *lsp-core*
@@ -541,8 +642,12 @@ 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}      (integer) Buffer handle, or 0 for current
+      • {client_id}  (integer) Client id
+
+    Return: ~
+        (boolean) success `true` if client was attached successfully; `false`
+        otherwise
 
 buf_detach_client({bufnr}, {client_id})          *vim.lsp.buf_detach_client()*
     Detaches client from the specified buffer. Note: While the server is
@@ -550,66 +655,65 @@ 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}      (integer) Buffer handle, or 0 for current
+      • {client_id}  (integer) 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}      (integer) Buffer handle, or 0 for current
+      • {client_id}  (integer) the client id
 
 buf_notify({bufnr}, {method}, {params})                 *vim.lsp.buf_notify()*
     Send a notification to a server
 
     Parameters: ~
-      • {bufnr}   (number|nil) The number of the buffer
+      • {bufnr}   (integer|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
+        (boolean) success true if any client returns true; false otherwise
 
                                                    *vim.lsp.buf_request_all()*
-buf_request_all({bufnr}, {method}, {params}, {callback})
-    Sends an async request for all active clients attached to the buffer.
-    Executes the callback on the combined result. Parameters are the same as
-    |vim.lsp.buf_request()| but the return result and callback are different.
+buf_request_all({bufnr}, {method}, {params}, {handler})
+    Sends an async request for all active clients attached to the buffer and
+    executes the `handler` callback with the combined result.
 
     Parameters: ~
-      • {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.
+      • {bufnr}    (integer) Buffer handle, or 0 for current.
+      • {method}   (string) LSP method name
+      • {params}   (table|nil) Parameters to send to the server
+      • {handler}  (function) Handler called after all requests are completed.
+                   Server results are passed as a `client_id:result` map.
 
     Return: ~
-        (function) A function that will cancel all requests which is the same
-        as the one returned from `buf_request`.
+        (function) cancel Function that cancels all requests.
 
                                                   *vim.lsp.buf_request_sync()*
 buf_request_sync({bufnr}, {method}, {params}, {timeout_ms})
     Sends a request to all server and waits for the response of all of them.
 
     Calls |vim.lsp.buf_request_all()| but blocks Nvim while awaiting the
-    result. Parameters are the same as |vim.lsp.buf_request()| but the return
-    result is different. Wait maximum of {timeout_ms} (default 1000) ms.
+    result. Parameters are the same as |vim.lsp.buf_request_all()| but the
+    result is different. Waits a maximum of {timeout_ms} (default 1000) ms.
 
     Parameters: ~
-      • {bufnr}       (number) Buffer handle, or 0 for current.
+      • {bufnr}       (integer) 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
+      • {timeout_ms}  (integer|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
-        `(nil, err)` where `err` is a string describing the failure reason.
+    Return (multiple): ~
+        (table) result Map of client_id:request_result.
+        (string|nil) err On timeout, cancel, or error, `err` is a string
+        describing the failure reason, and `result` is nil.
 
 client()                                                      *vim.lsp.client*
     LSP client object. You can get an active client object via
-    |vim.lsp.get_client_by_id()| or |vim.lsp.get_active_clients()|.
+    |vim.lsp.get_client_by_id()| or |vim.lsp.get_clients()|.
 
     • Methods:
       • request(method, params, [handler], bufnr) Sends a request to the
@@ -658,35 +762,42 @@ client()                                                      *vim.lsp.client*
         server. Entries are key-value pairs with the key being the request ID
         while the value is a table with `type`, `bufnr`, and `method`
         key-value pairs. `type` is either "pending" for an active request, or
-        "cancel" for a cancel request.
+        "cancel" for a cancel request. It will be "complete" ephemerally while
+        executing |LspRequest| autocmds when replies are received from the
+        server.
       • {config} (table): copy of the table that was passed by the user to
         |vim.lsp.start_client()|.
       • {server_capabilities} (table): Response from the server sent on
         `initialize` describing the server's capabilities.
+      • {progress} A ring buffer (|vim.ringbuf()|) containing progress
+        messages sent by the server.
 
 client_is_stopped({client_id})                   *vim.lsp.client_is_stopped()*
     Checks whether a client is stopped.
 
     Parameters: ~
-      • {client_id}  (number)
+      • {client_id}  (integer)
 
     Return: ~
-        true if client is stopped, false otherwise.
+        (boolean) stopped true if client is stopped, false otherwise.
 
-                                            *vim.lsp.for_each_buffer_client()*
-for_each_buffer_client({bufnr}, {fn})
-    Invokes a function for each LSP client attached to a buffer.
+commands                                                    *vim.lsp.commands*
+    Registry for client side commands. This is an extension point for plugins
+    to handle custom commands which are not part of the core language server
+    protocol specification.
 
-    Parameters: ~
-      • {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: >lua
+    The registry is a table where the key is a unique command name, and the
+    value is a function which is called if any LSP action (code action, code
+    lenses, ...) triggers the command.
 
-                   vim.lsp.for_each_buffer_client(0, function(client, client_id, bufnr)
-                     print(vim.inspect(client))
-                   end)
-<
+    If a LSP response contains a command for which no matching entry is
+    available in this registry, the command will be executed via the LSP
+    server using `workspace/executeCommand`.
+
+    The first argument to the function will be the `Command`: Command title:
+    String command: String arguments?: any[]
+
+    The second argument is the `ctx` of |lsp-handler|
 
 formatexpr({opts})                                      *vim.lsp.formatexpr()*
     Provides an interface between the built-in client and a `formatexpr`
@@ -694,8 +805,8 @@ formatexpr({opts})                                      *vim.lsp.formatexpr()*
 
     Currently only supports a single client. This can be set via `setlocal
     formatexpr=v:lua.vim.lsp.formatexpr()` but will typically or in
-    `on_attach` via `vim.api.nvim_buf_set_option(bufnr, 'formatexpr',
-    'v:lua.vim.lsp.formatexpr(#{timeout_ms:250})')`.
+    `on_attach` via `vim.bo[bufnr].formatexpr =
+    'v:lua.vim.lsp.formatexpr(#{timeout_ms:250})'`.
 
     Parameters: ~
       • {opts}  (table) options for customizing the formatting expression
@@ -703,62 +814,64 @@ formatexpr({opts})                                      *vim.lsp.formatexpr()*
                 • timeout_ms (default 500ms). The timeout period for the
                   formatting request.
 
-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
-                  returned clients. The available keys are:
-                  • id (number): Only return clients with the given id
-                  • bufnr (number): Only return clients attached to this
-                    buffer
-                  • name (string): Only return clients with the given name
-
-    Return: ~
-        (table) List of |vim.lsp.client| objects
-
                                           *vim.lsp.get_buffers_by_client_id()*
 get_buffers_by_client_id({client_id})
     Returns list of buffers attached to client_id.
 
     Parameters: ~
-      • {client_id}  (number) client id
+      • {client_id}  (integer) client id
 
     Return: ~
-        (list) of buffer ids
+        integer[] buffers 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}  (integer) client id
+
+    Return: ~
+        (nil|lsp.Client) client rpc object
+
+get_clients({filter})                                  *vim.lsp.get_clients()*
+    Get active clients.
+
+    Parameters: ~
+      • {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
+                    buffer
+                  • name (string): Only return clients with the given name
+                  • method (string): Only return clients supporting the given
+                    method
 
     Return: ~
-        |vim.lsp.client| object, or nil
+        lsp.Client []: List of |vim.lsp.client| objects
 
 get_log_path()                                        *vim.lsp.get_log_path()*
     Gets the path of the logfile used by the LSP client.
 
     Return: ~
-        (String) Path to logfile.
+        (string) path to log file
 
 omnifunc({findstart}, {base})                             *vim.lsp.omnifunc()*
     Implements 'omnifunc' compatible LSP completion.
 
     Parameters: ~
-      • {findstart}  (number) 0 or 1, decides behavior
-      • {base}       (number) findstart=0, text to match against
+      • {findstart}  (integer) 0 or 1, decides behavior
+      • {base}       (integer) findstart=0, text to match against
 
     Return: ~
-        (number) Decided by {findstart}:
+        integer|table Decided by {findstart}:
         • findstart=0: column where the completion starts, or -2 or -3
         • findstart=1: list of matches (actually just calls |complete()|)
 
     See also: ~
-        |complete-functions|
-        |complete-items|
-        |CompleteDone|
+      • |complete-functions|
+      • |complete-items|
+      • |CompleteDone|
 
 set_log_level({level})                               *vim.lsp.set_log_level()*
     Sets the global log level for LSP logging.
@@ -770,10 +883,10 @@ 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}  (integer|string) the case insensitive level name or number
 
     See also: ~
-        |vim.lsp.log_levels|
+      • |vim.lsp.log_levels|
 
 start({config}, {opts})                                      *vim.lsp.start()*
     Create a new LSP client and start a language server or reuses an already
@@ -781,12 +894,11 @@ start({config}, {opts})                                      *vim.lsp.start()*
     the current buffer to the client.
 
     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 |vim.lsp.start_client()| for all available options. The most important
@@ -818,7 +930,7 @@ start({config}, {opts})                                      *vim.lsp.start()*
     Parameters: ~
       • {config}  (table) Same configuration as documented in
                   |vim.lsp.start_client()|
-      • {opts}    nil|table Optional keyword arguments:
+      • {opts}    (nil|lsp.StartOpts) 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
@@ -827,7 +939,7 @@ start({config}, {opts})                                      *vim.lsp.start()*
                     re-using a client (0 for current).
 
     Return: ~
-        (number|nil) client_id
+        (integer|nil) client_id
 
 start_client({config})                                *vim.lsp.start_client()*
     Starts and initializes a client with the given configuration.
@@ -835,24 +947,23 @@ start_client({config})                                *vim.lsp.start_client()*
     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
+      • {config}  ( lsp.ClientConfig ) Configuration for the server:
+                  • cmd: (string[]|fun(dispatchers: table):table) command a
+                    list of strings 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: >
+                    spawn. Must be specified using a table. Non-string values
+                    are coerced to string. Example: >
 
-                       { "PRODUCTION=true"; "TEST=123"; PORT = 8080; HOST = "0.0.0.0"; }
+                       { 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
@@ -869,8 +980,7 @@ start_client({config})                                *vim.lsp.start_client()*
                     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.
+                      |vim.empty_dict()|, else it will be encoded as an array.
 
                   • handlers: Map of language server method names to
                     |lsp-handler|
@@ -912,8 +1022,8 @@ start_client({config})                                *vim.lsp.start_client()*
                     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
+                    sent client specified settings after initialization. Nvim
+                    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
@@ -946,27 +1056,34 @@ start_client({config})                                *vim.lsp.start_client()*
                     initialization.
 
     Return: ~
-        Client id. |vim.lsp.get_client_by_id()| Note: client may not be fully
-        initialized. Use `on_init` to do any actions once the client has been
-        initialized.
+        (integer|nil) client_id. |vim.lsp.get_client_by_id()| Note: client may
+        not be fully initialized. Use `on_init` to do any actions once the
+        client has been initialized.
+
+status()                                                    *vim.lsp.status()*
+    Consumes the latest progress messages from all clients and formats them as
+    a string. Empty if there are no clients or if no new messages
+
+    Return: ~
+        (string)
 
 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: >lua
-
-     vim.lsp.stop_client(vim.lsp.get_active_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_clients())
 <
 
     By default asks the server to shutdown, unless stop was requested already
     for this client, then force-shutdown is attempted.
 
     Parameters: ~
-      • {client_id}  number|table id or |vim.lsp.client| object, or list
+      • {client_id}  integer|table id or |vim.lsp.client| object, or list
                      thereof
       • {force}      (boolean|nil) shutdown forcefully
 
-tagfunc({...})                                             *vim.lsp.tagfunc()*
+tagfunc({pattern}, {flags})                                *vim.lsp.tagfunc()*
     Provides an interface between the built-in client and 'tagfunc'.
 
     When used with normal mode commands (e.g. |CTRL-]|) this will invoke the
@@ -979,7 +1096,7 @@ tagfunc({...})                                             *vim.lsp.tagfunc()*
       • {flags}    (string) See |tag-function|
 
     Return: ~
-        A list of matching tags
+        table[] tags A list of matching tags
 
 with({handler}, {override_config})                            *vim.lsp.with()*
     Function to manage overriding defaults for LSP handlers.
@@ -1008,7 +1125,8 @@ code_action({options})                             *vim.lsp.buf.code_action()*
       • {options}  (table|nil) Optional table which holds the following
                    optional fields:
                    • context: (table|nil) Corresponds to `CodeActionContext` of the LSP specification:
-                     • diagnostics (table|nil): LSP`Diagnostic[]` . Inferred from the current position if not provided.
+                     • diagnostics (table|nil): LSP `Diagnostic[]`. Inferred
+                       from the current position if not provided.
                      • only (table|nil): List of LSP `CodeActionKind`s used to
                        filter the code actions. Most language servers support
                        values like `refactor` or `quickfix`.
@@ -1023,38 +1141,39 @@ code_action({options})                             *vim.lsp.buf.code_action()*
                    • range: (table|nil) Range for which code actions should be
                      requested. If in visual mode this defaults to the active
                      selection. Table must contain `start` and `end` keys with
-                     {row, col} tuples using mark-like indexing. See
+                     {row,col} tuples using mark-like indexing. See
                      |api-indexing|
 
     See also: ~
-        https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeAction
-        vim.lsp.protocol.constants.CodeActionTriggerKind
+      • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeAction
+      • vim.lsp.protocol.CodeActionTriggerKind
 
 completion({context})                               *vim.lsp.buf.completion()*
     Retrieves the completion items at the current cursor position. Can only be
     called in Insert mode.
 
     Parameters: ~
-      • {context}  (context support not yet implemented) Additional
+      • {context}  (table) (context support not yet implemented) Additional
                    information about the context in which a completion was
                    triggered (how it was triggered, and by which trigger
                    character, if applicable)
 
     See also: ~
-        vim.lsp.protocol.constants.CompletionTriggerKind
+      • vim.lsp.protocol.CompletionTriggerKind
 
 declaration({options})                             *vim.lsp.buf.declaration()*
     Jumps to the declaration of the symbol under the cursor.
-    Note:
-        Many servers do not implement this method. Generally, see
+
+    Note: ~
+      • Many servers do not implement this method. Generally, see
         |vim.lsp.buf.definition()| instead.
 
     Parameters: ~
       • {options}  (table|nil) additional options
                    • reuse_win: (boolean) Jump to existing window if buffer is
                      already open.
-                   • on_list: (function) handler for list results. See
-                     |lsp-on-list-handler|
+                   • on_list: (function) |lsp-on-list-handler| replacing the
+                     default handler. Called for any non-empty result.
 
 definition({options})                               *vim.lsp.buf.definition()*
     Jumps to the definition of the symbol under the cursor.
@@ -1063,16 +1182,16 @@ definition({options})                               *vim.lsp.buf.definition()*
       • {options}  (table|nil) additional options
                    • reuse_win: (boolean) Jump to existing window if buffer is
                      already open.
-                   • on_list: (function) handler for list results. See
-                     |lsp-on-list-handler|
+                   • on_list: (function) |lsp-on-list-handler| replacing the
+                     default handler. Called for any non-empty result.
 
 document_highlight()                        *vim.lsp.buf.document_highlight()*
     Send request to the server to resolve document highlights for the current
     text document position. This request can be triggered by a key mapping or
-    by events such as `CursorHold` , e.g.: >vim
-      autocmd CursorHold  <buffer> lua vim.lsp.buf.document_highlight()
-      autocmd CursorHoldI <buffer> lua vim.lsp.buf.document_highlight()
-      autocmd CursorMoved <buffer> lua vim.lsp.buf.clear_references()
+    by events such as `CursorHold`, e.g.: >vim
+        autocmd CursorHold  <buffer> lua vim.lsp.buf.document_highlight()
+        autocmd CursorHoldI <buffer> lua vim.lsp.buf.document_highlight()
+        autocmd CursorMoved <buffer> lua vim.lsp.buf.clear_references()
 <
 
     Note: Usage of |vim.lsp.buf.document_highlight()| requires the following
@@ -1095,19 +1214,18 @@ execute_command({command_params})              *vim.lsp.buf.execute_command()*
       • {command_params}  (table) A valid `ExecuteCommandParams` object
 
     See also: ~
-        https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_executeCommand
+      • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_executeCommand
 
 format({options})                                       *vim.lsp.buf.format()*
     Formats a buffer using the attached (and optionally filtered) language
     server clients.
 
     Parameters: ~
-      • {options}  table|nil Optional table which holds the following optional
-                   fields:
+      • {options}  (table|nil) Optional table which holds the following
+                   optional fields:
                    • formatting_options (table|nil): Can be used to specify
                      FormattingOptions. Some unspecified options will be
-                     automatically derived from the current Neovim options.
-                     See https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#formattingOptions
+                     automatically derived from the current Nvim options. See https://microsoft.github.io/language-server-protocol/specification/#formattingOptions
                    • timeout_ms (integer|nil, default 1000): Time in
                      milliseconds to block for formatting requests. No effect
                      if async=true
@@ -1116,12 +1234,12 @@ format({options})                                       *vim.lsp.buf.format()*
                      buffer (0).
                    • filter (function|nil): Predicate used to filter clients.
                      Receives a client as argument and must return a boolean.
-                     Clients matching the predicate are included. Example:               • >lua
+                     Clients matching the predicate are included. Example: >lua
 
-              -- Never request typescript-language-server for formatting
-              vim.lsp.buf.format {
-                filter = function(client) return client.name ~= "tsserver" end
-              }
+                         -- Never request typescript-language-server for formatting
+                         vim.lsp.buf.format {
+                           filter = function(client) return client.name ~= "tsserver" end
+                         }
 <
                    • async boolean|nil If true the method won't block.
                      Defaults to false. Editing the buffer while formatting
@@ -1131,7 +1249,7 @@ format({options})                                       *vim.lsp.buf.format()*
                    • name (string|nil): Restrict formatting to the client with
                      name (client.name) matching this field.
                    • range (table|nil) Range to format. Table must contain
-                     `start` and `end` keys with {row, col} tuples using (1,0)
+                     `start` and `end` keys with {row,col} tuples using (1,0)
                      indexing. Defaults to current selection in visual mode
                      Defaults to `nil` in other modes, formatting the full
                      buffer
@@ -1146,8 +1264,8 @@ implementation({options})                       *vim.lsp.buf.implementation()*
 
     Parameters: ~
       • {options}  (table|nil) additional options
-                   • on_list: (function) handler for list results. See
-                     |lsp-on-list-handler|
+                   • on_list: (function) |lsp-on-list-handler| replacing the
+                     default handler. Called for any non-empty result.
 
 incoming_calls()                                *vim.lsp.buf.incoming_calls()*
     Lists all the call sites of the symbol under the cursor in the |quickfix|
@@ -1173,7 +1291,7 @@ references({context}, {options})                    *vim.lsp.buf.references()*
                      |lsp-on-list-handler|
 
     See also: ~
-        https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_references
+      • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_references
 
                                        *vim.lsp.buf.remove_workspace_folder()*
 remove_workspace_folder({workspace_folder})
@@ -1193,13 +1311,6 @@ rename({new_name}, {options})                           *vim.lsp.buf.rename()*
                     • name (string|nil): Restrict clients used for rename to
                       ones where client.name matches this field.
 
-server_ready()                                    *vim.lsp.buf.server_ready()*
-    Checks whether the language servers attached to the current buffer are
-    ready.
-
-    Return: ~
-        `true` if server responds.
-
 signature_help()                                *vim.lsp.buf.signature_help()*
     Displays signature information about the symbol under the cursor in a
     floating window.
@@ -1211,8 +1322,8 @@ type_definition({options})                     *vim.lsp.buf.type_definition()*
       • {options}  (table|nil) additional options
                    • reuse_win: (boolean) Jump to existing window if buffer is
                      already open.
-                   • on_list: (function) handler for list results. See
-                     |lsp-on-list-handler|
+                   • on_list: (function) |lsp-on-list-handler| replacing the
+                     default handler. Called for any non-empty result.
 
 workspace_symbol({query}, {options})          *vim.lsp.buf.workspace_symbol()*
     Lists all symbols in the current workspace in the quickfix window.
@@ -1222,7 +1333,7 @@ workspace_symbol({query}, {options})          *vim.lsp.buf.workspace_symbol()*
     string means no filtering is done.
 
     Parameters: ~
-      • {query}    (string, optional)
+      • {query}    (string|nil) optional
       • {options}  (table|nil) additional options
                    • on_list: (function) handler for list results. See
                      |lsp-on-list-handler|
@@ -1231,12 +1342,43 @@ workspace_symbol({query}, {options})          *vim.lsp.buf.workspace_symbol()*
 ==============================================================================
 Lua module: vim.lsp.diagnostic                                *lsp-diagnostic*
 
-get_namespace({client_id})                *vim.lsp.diagnostic.get_namespace()*
+                                          *vim.lsp.diagnostic.get_namespace()*
+get_namespace({client_id}, {is_pull})
     Get the diagnostic namespace associated with an LSP client
-    |vim.diagnostic|.
+    |vim.diagnostic| for diagnostics
+
+    Parameters: ~
+      • {client_id}  (integer) The id of the LSP client
+      • {is_pull}    boolean? Whether the namespace is for a pull or push
+                     client. Defaults to push
+
+                                          *vim.lsp.diagnostic.on_diagnostic()*
+on_diagnostic({_}, {result}, {ctx}, {config})
+    |lsp-handler| for the method "textDocument/diagnostic"
+
+    See |vim.diagnostic.config()| for configuration options. Handler-specific
+    configuration can be set using |vim.lsp.with()|: >lua
+        vim.lsp.handlers["textDocument/diagnostic"] = vim.lsp.with(
+          vim.lsp.diagnostic.on_diagnostic, {
+            -- Enable underline, use default values
+            underline = true,
+            -- Enable virtual text, override spacing to 4
+            virtual_text = {
+              spacing = 4,
+            },
+            -- Use a function to dynamically turn signs off
+            -- and on, using buffer local variables
+            signs = function(namespace, bufnr)
+              return vim.b[bufnr].show_signs == true
+            end,
+            -- Disable a feature
+            update_in_insert = false,
+          }
+        )
+<
 
     Parameters: ~
-      • {client_id}  (number) The id of the LSP client
+      • {config}  (table) Configuration table (see |vim.diagnostic.config()|).
 
                                  *vim.lsp.diagnostic.on_publish_diagnostics()*
 on_publish_diagnostics({_}, {result}, {ctx}, {config})
@@ -1244,24 +1386,23 @@ on_publish_diagnostics({_}, {result}, {ctx}, {config})
 
     See |vim.diagnostic.config()| for configuration options. Handler-specific
     configuration can be set using |vim.lsp.with()|: >lua
-
-     vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with(
-       vim.lsp.diagnostic.on_publish_diagnostics, {
-         -- Enable underline, use default values
-         underline = true,
-         -- Enable virtual text, override spacing to 4
-         virtual_text = {
-           spacing = 4,
-         },
-         -- Use a function to dynamically turn signs off
-         -- and on, using buffer local variables
-         signs = function(namespace, bufnr)
-           return vim.b[bufnr].show_signs == true
-         end,
-         -- Disable a feature
-         update_in_insert = false,
-       }
-     )
+        vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with(
+          vim.lsp.diagnostic.on_publish_diagnostics, {
+            -- Enable underline, use default values
+            underline = true,
+            -- Enable virtual text, override spacing to 4
+            virtual_text = {
+              spacing = 4,
+            },
+            -- Use a function to dynamically turn signs off
+            -- and on, using buffer local variables
+            signs = function(namespace, bufnr)
+              return vim.b[bufnr].show_signs == true
+            end,
+            -- Disable a feature
+            update_in_insert = false,
+          }
+        )
 <
 
     Parameters: ~
@@ -1275,25 +1416,26 @@ clear({client_id}, {bufnr})                         *vim.lsp.codelens.clear()*
     Clear the lenses
 
     Parameters: ~
-      • {client_id}  (number|nil) filter by client_id. All clients if nil
-      • {bufnr}      (number|nil) filter by buffer. All buffers if nil
+      • {client_id}  (integer|nil) filter by client_id. All clients if nil
+      • {bufnr}      (integer|nil) filter by buffer. All buffers if nil
 
 display({lenses}, {bufnr}, {client_id})           *vim.lsp.codelens.display()*
     Display the lenses using virtual text
 
     Parameters: ~
-      • {lenses}     (table) of lenses to display (`CodeLens[] | null`)
-      • {bufnr}      (number)
-      • {client_id}  (number)
+      • {lenses}     lsp.CodeLens[]|nil lenses to display
+      • {bufnr}      (integer)
+      • {client_id}  (integer)
 
 get({bufnr})                                          *vim.lsp.codelens.get()*
     Return all lenses for the given buffer
 
     Parameters: ~
-      • {bufnr}  (number) Buffer number. 0 can be used for the current buffer.
+      • {bufnr}  (integer) Buffer number. 0 can be used for the current
+                 buffer.
 
     Return: ~
-        (table) (`CodeLens[]`)
+        lsp.CodeLens[]
 
                                               *vim.lsp.codelens.on_codelens()*
 on_codelens({err}, {result}, {ctx}, {_})
@@ -1305,7 +1447,7 @@ refresh()                                         *vim.lsp.codelens.refresh()*
     It is recommended to trigger this using an autocmd or via keymap.
 
     Example: >vim
-      autocmd BufEnter,CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh()
+        autocmd BufEnter,CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh()
 <
 
 run()                                                 *vim.lsp.codelens.run()*
@@ -1315,9 +1457,64 @@ save({lenses}, {bufnr}, {client_id})                 *vim.lsp.codelens.save()*
     Store lenses for a specific buffer and client
 
     Parameters: ~
-      • {lenses}     (table) of lenses to store (`CodeLens[] | null`)
-      • {bufnr}      (number)
-      • {client_id}  (number)
+      • {lenses}     lsp.CodeLens[]|nil lenses to store
+      • {bufnr}      (integer)
+      • {client_id}  (integer)
+
+
+==============================================================================
+Lua module: vim.lsp.inlay_hint                                *lsp-inlay_hint*
+
+enable({bufnr}, {enable})                        *vim.lsp.inlay_hint.enable()*
+    Enable/disable/toggle inlay hints for a buffer
+
+    Note: ~
+        This API is pre-release (unstable).
+
+    Parameters: ~
+      • {bufnr}   (integer|nil) Buffer handle, or 0 or nil for current
+      • {enable}  (boolean|nil) true/nil to enable, false to disable
+
+get({filter})                                       *vim.lsp.inlay_hint.get()*
+    Get the list of inlay hints, (optionally) restricted by buffer or range.
+
+    Example usage: >lua
+        local hint = vim.lsp.inlay_hint.get({ bufnr = 0 })[1] -- 0 for current buffer
+
+        local client = vim.lsp.get_client_by_id(hint.client_id)
+        resolved_hint = client.request_sync('inlayHint/resolve', hint.inlay_hint, 100, 0).result
+        vim.lsp.util.apply_text_edits(resolved_hint.textEdits, 0, client.encoding)
+
+        location = resolved_hint.label[1].location
+        client.request('textDocument/hover', {
+          textDocument = { uri = location.uri },
+          position = location.range.start,
+        })
+<
+
+    Note: ~
+        This API is pre-release (unstable).
+
+    Parameters: ~
+      • {filter}  vim.lsp.inlay_hint.get.filter ? Optional filters |kwargs|:
+                  • bufnr (integer?): 0 for current buffer
+                  • range (lsp.Range?)
+
+    Return: ~
+        vim.lsp.inlay_hint.get.ret [] Each list item is a table with the following fields:
+        • bufnr (integer)
+        • client_id (integer)
+        • inlay_hint (lsp.InlayHint)
+
+is_enabled({bufnr})                          *vim.lsp.inlay_hint.is_enabled()*
+    Note: ~
+        This API is pre-release (unstable).
+
+    Parameters: ~
+      • {bufnr}  (integer|nil) Buffer handle, or 0 or nil for current
+
+    Return: ~
+        (boolean)
 
 
 ==============================================================================
@@ -1330,7 +1527,8 @@ force_refresh({bufnr})               *vim.lsp.semantic_tokens.force_refresh()*
     highlighting (|vim.lsp.semantic_tokens.start()| has been called for it)
 
     Parameters: ~
-      • {bufnr}  (nil|number) default: current buffer
+      • {bufnr}  (integer|nil) filter by buffer. All buffers if nil, current
+                 buffer if 0
 
                                         *vim.lsp.semantic_tokens.get_at_pos()*
 get_at_pos({bufnr}, {row}, {col})
@@ -1338,12 +1536,39 @@ get_at_pos({bufnr}, {row}, {col})
     arguments, returns the token under the cursor.
 
     Parameters: ~
-      • {bufnr}  (number|nil) Buffer number (0 for current buffer, default)
-      • {row}    (number|nil) Position row (default cursor position)
-      • {col}    (number|nil) Position column (default cursor position)
+      • {bufnr}  (integer|nil) Buffer number (0 for current buffer, default)
+      • {row}    (integer|nil) Position row (default cursor position)
+      • {col}    (integer|nil) Position column (default cursor position)
 
     Return: ~
-        (table|nil) List of tokens at position
+        (table|nil) List of tokens at position. Each token has the following
+        fields:
+        • line (integer) line number, 0-based
+        • start_col (integer) start column, 0-based
+        • end_col (integer) end column, 0-based
+        • type (string) token type as string, e.g. "variable"
+        • modifiers (table) token modifiers as a set. E.g., { static = true,
+          readonly = true }
+
+                                   *vim.lsp.semantic_tokens.highlight_token()*
+highlight_token({token}, {bufnr}, {client_id}, {hl_group}, {opts})
+    Highlight a semantic token.
+
+    Apply an extmark with a given highlight group for a semantic token. The
+    mark will be deleted by the semantic token engine when appropriate; for
+    example, when the LSP sends updated tokens. This function is intended for
+    use inside |LspTokenUpdate| callbacks.
+
+    Parameters: ~
+      • {token}      (table) a semantic token, found as `args.data.token` in
+                     |LspTokenUpdate|.
+      • {bufnr}      (integer) the buffer to highlight
+      • {client_id}  (integer) The ID of the |vim.lsp.client|
+      • {hl_group}   (string) Highlight group name
+      • {opts}       (table|nil) Optional parameters.
+                     • priority: (integer|nil) Priority for the applied
+                       extmark. Defaults to
+                       `vim.highlight.priorities.semantic_tokens + 3`
 
 start({bufnr}, {client_id}, {opts})          *vim.lsp.semantic_tokens.start()*
     Start the semantic token highlighting engine for the given buffer with the
@@ -1354,15 +1579,14 @@ start({bufnr}, {client_id}, {opts})          *vim.lsp.semantic_tokens.start()*
     server that supports it, you can delete the semanticTokensProvider table
     from the {server_capabilities} of your client in your |LspAttach| callback
     or your configuration's `on_attach` callback: >lua
-
-       client.server_capabilities.semanticTokensProvider = nil
+        client.server_capabilities.semanticTokensProvider = nil
 <
 
     Parameters: ~
-      • {bufnr}      (number)
-      • {client_id}  (number)
+      • {bufnr}      (integer)
+      • {client_id}  (integer)
       • {opts}       (nil|table) Optional keyword arguments
-                     • debounce (number, default: 200): Debounce token
+                     • debounce (integer, default: 200): Debounce token
                        requests to the server by the given number in
                        milliseconds
 
@@ -1376,8 +1600,8 @@ stop({bufnr}, {client_id})                    *vim.lsp.semantic_tokens.stop()*
     from the buffer.
 
     Parameters: ~
-      • {bufnr}      (number)
-      • {client_id}  (number)
+      • {bufnr}      (integer)
+      • {client_id}  (integer)
 
 
 ==============================================================================
@@ -1385,41 +1609,44 @@ Lua module: vim.lsp.handlers                                    *lsp-handlers*
 
 hover({_}, {result}, {ctx}, {config})               *vim.lsp.handlers.hover()*
     |lsp-handler| for the method "textDocument/hover" >lua
-
-       vim.lsp.handlers["textDocument/hover"] = vim.lsp.with(
-         vim.lsp.handlers.hover, {
-           -- Use a sharp border with `FloatBorder` highlights
-           border = "single",
-           -- add the title in hover float window
-           title = "hover"
-         }
-       )
+        vim.lsp.handlers["textDocument/hover"] = vim.lsp.with(
+          vim.lsp.handlers.hover, {
+            -- Use a sharp border with `FloatBorder` highlights
+            border = "single",
+            -- add the title in hover float window
+            title = "hover"
+          }
+        )
 <
 
     Parameters: ~
       • {config}  (table) Configuration table.
                   • border: (default=nil)
                     • Add borders to the floating window
-                    • See |nvim_open_win()|
+                    • See |vim.lsp.util.open_floating_preview()| for more
+                      options.
 
                                            *vim.lsp.handlers.signature_help()*
 signature_help({_}, {result}, {ctx}, {config})
-    |lsp-handler| for the method "textDocument/signatureHelp". The active
-    parameter is highlighted with |hl-LspSignatureActiveParameter|. >lua
-
-       vim.lsp.handlers["textDocument/signatureHelp"] = vim.lsp.with(
-         vim.lsp.handlers.signature_help, {
-           -- Use a sharp border with `FloatBorder` highlights
-           border = "single"
-         }
-       )
+    |lsp-handler| for the method "textDocument/signatureHelp".
+
+    The active parameter is highlighted with |hl-LspSignatureActiveParameter|. >lua
+        vim.lsp.handlers["textDocument/signatureHelp"] = vim.lsp.with(
+          vim.lsp.handlers.signature_help, {
+            -- Use a sharp border with `FloatBorder` highlights
+            border = "single"
+          }
+        )
 <
 
     Parameters: ~
+      • {result}  (table) Response from the language server
+      • {ctx}     (table) Client context
       • {config}  (table) Configuration table.
                   • border: (default=nil)
                     • Add borders to the floating window
-                    • See |nvim_open_win()|
+                    • See |vim.lsp.util.open_floating_preview()| for more
+                      options
 
 
 ==============================================================================
@@ -1432,11 +1659,11 @@ apply_text_document_edit({text_document_edit}, {index}, {offset_encoding})
 
     Parameters: ~
       • {text_document_edit}  (table) a `TextDocumentEdit` object
-      • {index}               (number) Optional index of the edit, if from a
+      • {index}               (integer) Optional index of the edit, if from a
                               list of edits (or nil, if not from a list)
 
     See also: ~
-        https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentEdit
+      • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentEdit
 
                                              *vim.lsp.util.apply_text_edits()*
 apply_text_edits({text_edits}, {bufnr}, {offset_encoding})
@@ -1444,11 +1671,11 @@ apply_text_edits({text_edits}, {bufnr}, {offset_encoding})
 
     Parameters: ~
       • {text_edits}       (table) list of `TextEdit` objects
-      • {bufnr}            (number) Buffer id
+      • {bufnr}            (integer) Buffer id
       • {offset_encoding}  (string) utf-8|utf-16|utf-32
 
     See also: ~
-        https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textEdit
+      • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textEdit
 
                                          *vim.lsp.util.apply_workspace_edit()*
 apply_workspace_edit({workspace_edit}, {offset_encoding})
@@ -1462,35 +1689,35 @@ buf_clear_references({bufnr})            *vim.lsp.util.buf_clear_references()*
     Removes document highlights from a buffer.
 
     Parameters: ~
-      • {bufnr}  (number) Buffer id
+      • {bufnr}  (integer|nil) Buffer id
 
                                      *vim.lsp.util.buf_highlight_references()*
 buf_highlight_references({bufnr}, {references}, {offset_encoding})
     Shows a list of document highlights for a certain buffer.
 
     Parameters: ~
-      • {bufnr}            (number) Buffer id
+      • {bufnr}            (integer) Buffer id
       • {references}       (table) List of `DocumentHighlight` objects to
                            highlight
       • {offset_encoding}  (string) One of "utf-8", "utf-16", "utf-32".
 
     See also: ~
-        https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocumentContentChangeEvent
+      • https://microsoft.github.io/language-server-protocol/specification/#textDocumentContentChangeEvent
 
                                              *vim.lsp.util.character_offset()*
 character_offset({buf}, {row}, {col}, {offset_encoding})
     Returns the UTF-32 and UTF-16 offsets for a position in a certain buffer.
 
     Parameters: ~
-      • {buf}              (number) buffer number (0 for current)
+      • {buf}              (integer) buffer number (0 for current)
       • {row}              0-indexed line
       • {col}              0-indexed byte offset in line
-      • {offset_encoding}  (string) utf-8|utf-16|utf-32|nil defaults to
+      • {offset_encoding}  (string) utf-8|utf-16|utf-32 defaults to
                            `offset_encoding` of first client of `buf`
 
     Return: ~
-        (number, number) `offset_encoding` index of the character in line
-        {row} column {col} in buffer {buf}
+        (integer) `offset_encoding` index of the character in line {row}
+        column {col} in buffer {buf}
 
                               *vim.lsp.util.convert_input_to_markdown_lines()*
 convert_input_to_markdown_lines({input}, {contents})
@@ -1499,58 +1726,50 @@ convert_input_to_markdown_lines({input}, {contents})
     window for `textDocument/hover`, for parsing the result of
     `textDocument/signatureHelp`, and potentially others.
 
+    Note that if the input is of type `MarkupContent` and its kind is
+    `plaintext`, then the corresponding value is returned without further
+    modifications.
+
     Parameters: ~
       • {input}     (`MarkedString` | `MarkedString[]` | `MarkupContent`)
       • {contents}  (table|nil) List of strings to extend with converted
                     lines. Defaults to {}.
 
     Return: ~
-        {contents}, extended with lines of converted markdown.
+        string[] extended with lines of converted markdown.
 
     See also: ~
-        https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover
+      • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover
 
                      *vim.lsp.util.convert_signature_help_to_markdown_lines()*
 convert_signature_help_to_markdown_lines({signature_help}, {ft}, {triggers})
-    Converts `textDocument/SignatureHelp` response to markdown lines.
+    Converts `textDocument/signatureHelp` response to markdown lines.
 
     Parameters: ~
-      • {signature_help}  Response of `textDocument/SignatureHelp`
-      • {ft}              optional filetype that will be use as the `lang` for
-                          the label markdown code block
-      • {triggers}        optional list of trigger characters from the lsp
+      • {signature_help}  (table) Response of `textDocument/SignatureHelp`
+      • {ft}              (string|nil) filetype that will be use as the `lang`
+                          for the label markdown code block
+      • {triggers}        (table|nil) list of trigger characters from the lsp
                           server. used to better determine parameter offsets
 
-    Return: ~
-        (list) of lines of converted markdown.
-
-    See also: ~
-        https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_signatureHelp
-
-                                     *vim.lsp.util.extract_completion_items()*
-extract_completion_items({result})
-    Can be used to extract the completion items from a `textDocument/completion` request, which may return one of `CompletionItem[]` , `CompletionList` or null.
-
-    Parameters: ~
-      • {result}  (table) The result of a `textDocument/completion` request
-
-    Return: ~
-        (table) List of completion items
+    Return (multiple): ~
+        (table|nil) table list of lines of converted markdown.
+        (table|nil) table of active hl
 
     See also: ~
-        https://microsoft.github.io/language-server-protocol/specification#textDocument_completion
+      • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_signatureHelp
 
 get_effective_tabstop({bufnr})          *vim.lsp.util.get_effective_tabstop()*
     Returns indentation size.
 
     Parameters: ~
-      • {bufnr}  (number|nil) Buffer handle, defaults to current
+      • {bufnr}  (integer|nil) Buffer handle, defaults to current
 
     Return: ~
-        (number) indentation size
+        (integer) indentation size
 
     See also: ~
-        'shiftwidth'
+      • 'shiftwidth'
 
                                              *vim.lsp.util.jump_to_location()*
 jump_to_location({location}, {offset_encoding}, {reuse_win})
@@ -1558,7 +1777,7 @@ jump_to_location({location}, {offset_encoding}, {reuse_win})
 
     Parameters: ~
       • {location}         (table) (`Location`|`LocationLink`)
-      • {offset_encoding}  "utf-8" | "utf-16" | "utf-32"
+      • {offset_encoding}  (string|nil) utf-8|utf-16|utf-32
       • {reuse_win}        (boolean|nil) Jump to existing window if buffer is
                            already open.
 
@@ -1570,13 +1789,17 @@ locations_to_items({locations}, {offset_encoding})
     Returns the items with the byte position calculated correctly and in
     sorted order, for display in quickfix and location lists.
 
+    The `user_data` field of each resulting item will contain the original
+    `Location` or `LocationLink` it was computed from.
+
     The result can be passed to the {list} argument of |setqflist()| or
     |setloclist()|.
 
     Parameters: ~
       • {locations}        (table) list of `Location`s or `LocationLink`s
       • {offset_encoding}  (string) offset_encoding for locations
-                           utf-8|utf-16|utf-32
+                           utf-8|utf-16|utf-32 default to first client of
+                           buffer
 
     Return: ~
         (table) list of items
@@ -1585,11 +1808,11 @@ lookup_section({settings}, {section})          *vim.lsp.util.lookup_section()*
     Helper function to return nested values in language server settings
 
     Parameters: ~
-      • {settings}  a table of language server settings
-      • {section}   a string indicating the field of the settings table
+      • {settings}  (table) language server settings
+      • {section}   string indicating the field of the settings table
 
     Return: ~
-        (table or string) The value of settings accessed via section
+        table|string The value of settings accessed via section
 
                                   *vim.lsp.util.make_floating_popup_options()*
 make_floating_popup_options({width}, {height}, {opts})
@@ -1597,15 +1820,22 @@ make_floating_popup_options({width}, {height}, {opts})
     table can be passed to |nvim_open_win()|.
 
     Parameters: ~
-      • {width}   (number) window width (in character cells)
-      • {height}  (number) window height (in character cells)
-      • {opts}    (table, optional)
-                  • offset_x (number) offset to add to `col`
-                  • offset_y (number) offset to add to `row`
+      • {width}   (integer) window width (in character cells)
+      • {height}  (integer) window height (in character cells)
+      • {opts}    (table) optional
+                  • offset_x (integer) offset to add to `col`
+                  • offset_y (integer) offset to add to `row`
                   • border (string or table) override `border`
                   • focusable (string or table) override `focusable`
                   • zindex (string or table) override `zindex`, defaults to 50
                   • relative ("mouse"|"cursor") defaults to "cursor"
+                  • anchor_bias ("auto"|"above"|"below") defaults to "auto"
+                    • "auto": place window based on which side of the cursor
+                      has more lines
+                    • "above": place the window above the cursor unless there
+                      are not enough lines to display the full window height.
+                    • "below": place the window below the cursor unless there
+                      are not enough lines to display the full window height.
 
     Return: ~
         (table) Options
@@ -1622,7 +1852,7 @@ make_formatting_params({options})
         `DocumentFormattingParams` object
 
     See also: ~
-        https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_formatting
+      • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_formatting
 
                                       *vim.lsp.util.make_given_range_params()*
 make_given_range_params({start_pos}, {end_pos}, {bufnr}, {offset_encoding})
@@ -1630,18 +1860,18 @@ make_given_range_params({start_pos}, {end_pos}, {bufnr}, {offset_encoding})
     similar to |vim.lsp.util.make_range_params()|.
 
     Parameters: ~
-      • {start_pos}        number[]|nil {row, col} mark-indexed position.
+      • {start_pos}        integer[]|nil {row,col} mark-indexed position.
                            Defaults to the start of the last visual selection.
-      • {end_pos}          number[]|nil {row, col} mark-indexed position.
+      • {end_pos}          integer[]|nil {row,col} mark-indexed position.
                            Defaults to the end of the last visual selection.
-      • {bufnr}            (number|nil) buffer handle or 0 for current,
+      • {bufnr}            (integer|nil) buffer handle or 0 for current,
                            defaults to current
       • {offset_encoding}  "utf-8"|"utf-16"|"utf-32"|nil defaults to
                            `offset_encoding` of first client of `bufnr`
 
     Return: ~
-        { textDocument = { uri = `current_file_uri` }, range = { start =
-        `start_position`, end = `end_position` } }
+        (table) { textDocument = { uri = `current_file_uri` }, range = { start
+        = `start_position`, end = `end_position` } }
 
                                          *vim.lsp.util.make_position_params()*
 make_position_params({window}, {offset_encoding})
@@ -1649,17 +1879,17 @@ make_position_params({window}, {offset_encoding})
     cursor position.
 
     Parameters: ~
-      • {window}           (number|nil) window handle or 0 for current,
+      • {window}           (integer|nil) window handle or 0 for current,
                            defaults to current
       • {offset_encoding}  (string|nil) utf-8|utf-16|utf-32|nil defaults to
                            `offset_encoding` of first client of buffer of
                            `window`
 
     Return: ~
-        `TextDocumentPositionParams` object
+        (table) `TextDocumentPositionParams` object
 
     See also: ~
-        https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentPositionParams
+      • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentPositionParams
 
                                             *vim.lsp.util.make_range_params()*
 make_range_params({window}, {offset_encoding})
@@ -1669,36 +1899,36 @@ make_range_params({window}, {offset_encoding})
     `textDocument/rangeFormatting`.
 
     Parameters: ~
-      • {window}           (number|nil) window handle or 0 for current,
+      • {window}           (integer|nil) window handle or 0 for current,
                            defaults to current
       • {offset_encoding}  "utf-8"|"utf-16"|"utf-32"|nil defaults to
                            `offset_encoding` of first client of buffer of
                            `window`
 
     Return: ~
-        { textDocument = { uri = `current_file_uri` }, range = { start =
-        `current_position`, end = `current_position` } }
+        (table) { textDocument = { uri = `current_file_uri` }, range = { start
+        = `current_position`, end = `current_position` } }
 
                                     *vim.lsp.util.make_text_document_params()*
 make_text_document_params({bufnr})
     Creates a `TextDocumentIdentifier` object for the current buffer.
 
     Parameters: ~
-      • {bufnr}  (number|nil) Buffer handle, defaults to current
+      • {bufnr}  (integer|nil) Buffer handle, defaults to current
 
     Return: ~
-        `TextDocumentIdentifier`
+        (table) `TextDocumentIdentifier`
 
     See also: ~
-        https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentIdentifier
+      • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentIdentifier
 
                                         *vim.lsp.util.make_workspace_params()*
 make_workspace_params({added}, {removed})
     Create the workspace params
 
     Parameters: ~
-      • {added}    
-      • {removed}
+      • {added}    (table)
+      • {removed}  (table)
 
                                         *vim.lsp.util.open_floating_preview()*
 open_floating_preview({contents}, {syntax}, {opts})
@@ -1707,18 +1937,16 @@ open_floating_preview({contents}, {syntax}, {opts})
     Parameters: ~
       • {contents}  (table) of lines to show in window
       • {syntax}    (string) of syntax to set for opened buffer
-      • {opts}      (table) with optional fields (additional keys are passed
-                    on to |nvim_open_win()|)
-                    • height: (number) height of floating window
-                    • width: (number) width of floating window
+      • {opts}      (table) with optional fields (additional keys are filtered
+                    with |vim.lsp.util.make_floating_popup_options()| before
+                    they are passed on to |nvim_open_win()|)
+                    • height: (integer) height of floating window
+                    • width: (integer) width of floating window
                     • wrap: (boolean, default true) wrap long lines
-                    • wrap_at: (number) character to wrap at for computing
+                    • wrap_at: (integer) character to wrap at for computing
                       height when wrap is enabled
-                    • max_width: (number) maximal width of floating window
-                    • max_height: (number) maximal height of floating window
-                    • pad_top: (number) number of lines to pad contents at top
-                    • pad_bottom: (number) number of lines to pad contents at
-                      bottom
+                    • max_width: (integer) maximal width of floating window
+                    • max_height: (integer) maximal height of floating window
                     • focus_id: (string) if a popup with this id is opened,
                       then focus it
                     • close_events: (table) list of events that closes the
@@ -1728,18 +1956,9 @@ open_floating_preview({contents}, {syntax}, {opts})
                       {focusable} is also `true`, focus an existing floating
                       window with the same {focus_id}
 
-    Return: ~
-        bufnr,winnr buffer and window number of the newly created floating
-        preview window
-
-parse_snippet({input})                          *vim.lsp.util.parse_snippet()*
-    Parses snippets in a completion entry.
-
-    Parameters: ~
-      • {input}  (string) unparsed snippet
-
-    Return: ~
-        (string) parsed snippet
+    Return (multiple): ~
+        (integer) bufnr of newly created float window
+        (integer) winid of newly created float window preview window
 
 preview_location({location}, {opts})         *vim.lsp.util.preview_location()*
     Previews a location in a floating window
@@ -1750,10 +1969,11 @@ preview_location({location}, {opts})         *vim.lsp.util.preview_location()*
       definition)
 
     Parameters: ~
-      • {location}  a single `Location` or `LocationLink`
+      • {location}  (table) a single `Location` or `LocationLink`
 
-    Return: ~
-        (bufnr,winnr) buffer and window number of floating window or nil
+    Return (multiple): ~
+        (integer|nil) buffer id of float window
+        (integer|nil) window id of float window
 
 rename({old_fname}, {new_fname}, {opts})               *vim.lsp.util.rename()*
     Rename old_fname to new_fname
@@ -1761,27 +1981,13 @@ rename({old_fname}, {new_fname}, {opts})               *vim.lsp.util.rename()*
     Parameters: ~
       • {opts}  (table)
 
-set_lines({lines}, {A}, {B}, {new_lines})           *vim.lsp.util.set_lines()*
-    Replaces text in a range with new text.
-
-    CAUTION: Changes in-place!
-
-    Parameters: ~
-      • {lines}      (table) Original list of strings
-      • {A}          (table) Start position; a 2-tuple of {line, col} numbers
-      • {B}          (table) End position; a 2-tuple of {line, col} numbers
-      • {new_lines}  A list of strings to replace the original
-
-    Return: ~
-        (table) The modified {lines} object
-
                                                 *vim.lsp.util.show_document()*
 show_document({location}, {offset_encoding}, {opts})
     Shows document and optionally jumps to the location.
 
     Parameters: ~
       • {location}         (table) (`Location`|`LocationLink`)
-      • {offset_encoding}  "utf-8" | "utf-16" | "utf-32"
+      • {offset_encoding}  (string|nil) utf-8|utf-16|utf-32
       • {opts}             (table|nil) options
                            • reuse_win (boolean) Jump to existing window if
                              buffer is already open.
@@ -1805,63 +2011,22 @@ stylize_markdown({bufnr}, {contents}, {opts})
 
     Parameters: ~
       • {contents}  (table) of lines to show in window
-      • {opts}      dictionary with optional fields
+      • {opts}      (table) with optional fields
                     • height of floating window
                     • width of floating window
                     • wrap_at character to wrap at for computing height
                     • max_width maximal width of floating window
                     • max_height maximal height of floating window
-                    • pad_top number of lines to pad contents at top
-                    • pad_bottom number of lines to pad contents at bottom
                     • separator insert separator after code block
 
     Return: ~
-        width,height size of float
+        (table) stripped content
 
 symbols_to_items({symbols}, {bufnr})         *vim.lsp.util.symbols_to_items()*
     Converts symbols to quickfix list items.
 
     Parameters: ~
-      • {symbols}  DocumentSymbol[] or SymbolInformation[]
-
-              *vim.lsp.util.text_document_completion_list_to_complete_items()*
-text_document_completion_list_to_complete_items({result}, {prefix})
-    Turns the result of a `textDocument/completion` request into
-    vim-compatible |complete-items|.
-
-    Parameters: ~
-      • {result}  The result of a `textDocument/completion` call, e.g. from
-                  |vim.lsp.buf.completion()|, which may be one of
-                  `CompletionItem[]`, `CompletionList` or `null`
-      • {prefix}  (string) the prefix to filter the completion items
-
-    Return: ~
-        { matches = complete-items table, incomplete = bool }
-
-    See also: ~
-        |complete-items|
-
-trim_empty_lines({lines})                    *vim.lsp.util.trim_empty_lines()*
-    Removes empty lines from the beginning and end.
-
-    Parameters: ~
-      • {lines}  (table) list of lines to trim
-
-    Return: ~
-        (table) trimmed list of lines
-
-                                *vim.lsp.util.try_trim_markdown_code_blocks()*
-try_trim_markdown_code_blocks({lines})
-    Accepts markdown lines and tries to reduce them to a filetype if they
-    comprise just a single code block.
-
-    CAUTION: Modifies the input in-place!
-
-    Parameters: ~
-      • {lines}  (table) list of lines
-
-    Return: ~
-        (string) filetype or "markdown" if it was unchanged.
+      • {symbols}  (table) DocumentSymbol[] or SymbolInformation[]
 
 
 ==============================================================================
@@ -1877,7 +2042,7 @@ get_level()                                          *vim.lsp.log.get_level()*
     Gets the current log level.
 
     Return: ~
-        (string) current log level
+        (integer) current log level
 
 set_format_func({handle})                      *vim.lsp.log.set_format_func()*
     Sets formatting function used to format logs
@@ -1890,13 +2055,13 @@ set_level({level})                                   *vim.lsp.log.set_level()*
     Sets the current log level.
 
     Parameters: ~
-      • {level}  (string|number) One of `vim.lsp.log.levels`
+      • {level}  (string|integer) One of `vim.lsp.log.levels`
 
 should_log({level})                                 *vim.lsp.log.should_log()*
     Checks whether the level is sufficient for logging.
 
     Parameters: ~
-      • {level}  (number) log level
+      • {level}  (integer) log level
 
     Return: ~
         (bool) true if would log, false if not
@@ -1911,7 +2076,7 @@ connect({host}, {port})                                *vim.lsp.rpc.connect()*
 
     Parameters: ~
       • {host}  (string)
-      • {port}  (number)
+      • {port}  (integer)
 
     Return: ~
         (function)
@@ -1933,7 +2098,7 @@ notify({method}, {params})                              *vim.lsp.rpc.notify()*
       • {params}  (table|nil) Parameters for the invoked LSP method
 
     Return: ~
-        (bool) `true` if notification could be sent, `false` if not
+        (boolean) `true` if notification could be sent, `false` if not
 
                                                        *vim.lsp.rpc.request()*
 request({method}, {params}, {callback}, {notify_reply_callback})
@@ -1943,20 +2108,21 @@ request({method}, {params}, {callback}, {notify_reply_callback})
       • {method}                 (string) The invoked LSP method
       • {params}                 (table|nil) Parameters for the invoked LSP
                                  method
-      • {callback}               (function) Callback to invoke
+      • {callback}               fun(err: lsp.ResponseError | nil, result:
+                                 any) Callback to invoke
       • {notify_reply_callback}  (function|nil) Callback to invoke as soon as
                                  a request is no longer pending
 
     Return: ~
-        (bool, number) `(true, message_id)` if request could be sent, `false`
-        if not
+        (boolean) success, integer|nil request_id true, message_id if request
+        could be sent, `false` if not
 
                                             *vim.lsp.rpc.rpc_response_error()*
 rpc_response_error({code}, {message}, {data})
     Creates an RPC response object/table.
 
     Parameters: ~
-      • {code}     (number) RPC error code defined in
+      • {code}     (integer) RPC error code defined in
                    `vim.lsp.protocol.ErrorCodes`
       • {message}  (string|nil) arbitrary message to send to server
       • {data}     any|nil arbitrary data to send to server
@@ -1986,8 +2152,7 @@ start({cmd}, {cmd_args}, {dispatchers}, {extra_spawn_params})
                                 for LSP server process
 
     Return: ~
-        Client RPC object.
-        Methods:
+        (table|nil) Client RPC object, with these methods:
         • `notify()` |vim.lsp.rpc.notify()|
         • `request()` |vim.lsp.rpc.request()|
         • `is_closing()` returns a boolean indicating if the RPC is closing.
@@ -1995,27 +2160,6 @@ start({cmd}, {cmd_args}, {dispatchers}, {extra_spawn_params})
 
 
 ==============================================================================
-Lua module: vim.lsp.sync                                            *lsp-sync*
-
-                                                 *vim.lsp.sync.compute_diff()*
-compute_diff({___MissingCloseParenHere___})
-    Returns the range table for the difference between prev and curr lines
-
-    Parameters: ~
-      • {prev_lines}       (table) list of lines
-      • {curr_lines}       (table) list of lines
-      • {firstline}        (number) line to begin search for first difference
-      • {lastline}         (number) line to begin search in old_lines for last
-                           difference
-      • {new_lastline}     (number) line to begin search in new_lines for last
-                           difference
-      • {offset_encoding}  (string) encoding requested by language server
-
-    Return: ~
-        (table) TextDocumentContentChangeEvent see https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocumentContentChangeEvent
-
-
-==============================================================================
 Lua module: vim.lsp.protocol                                    *lsp-protocol*
 
                                  *vim.lsp.protocol.make_client_capabilities()*
@@ -2023,6 +2167,15 @@ make_client_capabilities()
     Gets a new ClientCapabilities object describing the LSP client
     capabilities.
 
+    Return: ~
+        lsp.ClientCapabilities
+
+Methods                                             *vim.lsp.protocol.Methods*
+    LSP method names.
+
+    See also: ~
+      • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#metaModel
+
                                      *vim.lsp.protocol.resolve_capabilities()*
 resolve_capabilities({server_capabilities})
     Creates a normalized object describing LSP server capabilities.
@@ -2032,6 +2185,6 @@ resolve_capabilities({server_capabilities})
                                server
 
     Return: ~
-        (table) Normalized table of capabilities
+        (table|nil) Normalized table of capabilities
 
  vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: