docs

ref neovim#23520

runtime/doc/builtin.txt

@@ -8842,10 +8842,13 @@ termopen({cmd} [, {opts}])			*termopen()*
 		to the current (unmodified) buffer. Parameters and behavior
 		are the same as |jobstart()| except "pty", "width", "height",
 		and "TERM" are ignored: "height" and "width" are taken from
-		the current window.
-		Returns the same values as |jobstart()|.
+		the current window. Note that termopen() implies a "pty" arg
+		to jobstart(), and thus has the implications documented at
+		|jobstart()|.
 
-		Terminal environment is initialized as in ||jobstart-env|,
+		Returns the same values as jobstart().
+
+		Terminal environment is initialized as in |jobstart-env|,
 		except $TERM is set to "xterm-256color". Full behavior is
 		described in |terminal|.
 

runtime/doc/deprecated.txt

@@ -117,6 +117,13 @@ internally and are no longer exposed as part of the API. Instead, use
 - *vim.lsp.diagnostic.set_virtual_text()*
 
 LSP FUNCTIONS
+- *vim.lsp.buf.server_ready()*
+  Use |LspAttach| instead, depending on your use-case. "Server ready" is not
+  part of the LSP spec, so the Nvim LSP client cannot meaningfully implement
+  it. "Ready" is ambiguous because:
+  - Language servers may finish analyzing the workspace, but edits can always
+    re-trigger analysis/builds.
+  - Language servers can serve some requests even while processing changes.
 - *vim.lsp.buf.range_code_action()*		Use |vim.lsp.buf.code_action()| with
 						the `range` parameter.
 - *vim.lsp.util.diagnostics_to_items()*		Use |vim.diagnostic.toqflist()| instead.

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.

runtime/lua/vim/lsp.lua

@@ -1491,7 +1491,7 @@ function lsp.start_client(config)
   ---successful, then it will return {request_id} as the
   ---second result. You can use this with `client.cancel_request(request_id)`
   ---to cancel the-request.
-  ---@see |vim.lsp.buf_request()|
+  ---@see |vim.lsp.buf_request_all()|
   function client.request(method, params, handler, bufnr)
     if not handler then
       handler = assert(
@@ -2119,22 +2119,19 @@ function lsp.buf_request(bufnr, method, params, handler)
   return client_request_ids, _cancel_all_requests
 end
 
----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.
+--- Sends an async request for all active clients attached to the buffer and executes the `handler`
+--- callback with the combined result.
 ---
 ---@param bufnr (integer) Buffer handle, or 0 for current.
 ---@param method (string) LSP method name
 ---@param params (table|nil) Parameters to send to the server
----@param callback fun(request_results: table<integer, {error: lsp.ResponseError, result: any}>) (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.
----
----@return fun() cancel A function that will cancel all requests
-function lsp.buf_request_all(bufnr, method, params, callback)
-  local request_results = {}
+---@param handler fun(results: table<integer, {error: lsp.ResponseError, result: any}>) (function)
+--- Handler called after all requests are completed. Server results are passed as
+--- a `client_id:result` map.
+---
+---@return fun() cancel Function that cancels all requests.
+function lsp.buf_request_all(bufnr, method, params, handler)
+  local results = {}
   local result_count = 0
   local expected_result_count = 0
 
@@ -2147,12 +2144,12 @@ function lsp.buf_request_all(bufnr, method, params, callback)
   end)
 
   local function _sync_handler(err, result, ctx)
-    request_results[ctx.client_id] = { error = err, result = result }
+    results[ctx.client_id] = { error = err, result = result }
     result_count = result_count + 1
     set_expected_result_count()
 
     if result_count >= expected_result_count then
-      callback(request_results)
+      handler(results)
     end
   end
 
@@ -2164,8 +2161,8 @@ end
 --- 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.
+--- Parameters are the same as |vim.lsp.buf_request_all()| but the result is
+--- different. Waits a maximum of {timeout_ms} (default 1000) ms.
 ---
 ---@param bufnr (integer) Buffer handle, or 0 for current.
 ---@param method (string) LSP method name

scripts/gen_help_html.lua

@@ -62,15 +62,13 @@ local exclude_invalid = {
   ["'string'"] = "eval.txt",
   Query = 'treesitter.txt',
   ['eq?'] = 'treesitter.txt',
-  ['lsp-request'] = 'lsp.txt',
   matchit = 'vim_diff.txt',
   ['matchit.txt'] = 'help.txt',
   ["set!"] = "treesitter.txt",
   ['v:_null_blob'] = 'builtin.txt',
   ['v:_null_dict'] = 'builtin.txt',
   ['v:_null_list'] = 'builtin.txt',
   ['v:_null_string'] = 'builtin.txt',
-  ['vim.lsp.buf_request()'] = 'lsp.txt',
   ['vim.lsp.util.get_progress_messages()'] = 'lsp.txt',
 }