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

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()*