1 files changed, 27 insertions, 36 deletions

diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 4f2c457107..ca4570e392 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -207,10 +207,10 @@ specification. These LSP requests/notifications are defined by default:
 
                                                                  *lsp-handler*
 
-lsp-handlers are functions with special signatures that are designed to handle
-responses and notifications from LSP servers.
+LSP handlers are functions with signatures designed to handle LSP responses
+and notifications.
 
-For |lsp-request|, each |lsp-handler| has this signature: >
+For |lsp-response|, each |lsp-handler| has this signature: >
 
   function(err, result, ctx, config)
 <
@@ -363,42 +363,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.
-
-    For example: >lua
+- The {handlers} parameter of |vim.lsp.start()|. This sets the default
+  |lsp-handler| for the server being started. 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.
-
-    For example: >lua
+- The {handler} parameter of |vim.lsp.buf_request_all()|. This sets
+  the |lsp-handler| ONLY for the given request(s). 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*
@@ -709,31 +704,27 @@ buf_notify({bufnr}, {method}, {params})                 *vim.lsp.buf_notify()*
         (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}     (integer) 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. Unlike `buf_request`, this will collect all the
-                    responses from each server instead of handling them. A map
-                    of client_id:request_result will be provided to the
-                    callback.
+      • {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: ~
-        fun() cancel A function that will cancel all requests
+        fun() 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}       (integer) Buffer handle, or 0 for current.