docs(lsp): remove lsp.buf_request from docs (#19738)

This starts a soft phase-out of `buf_request`.

`buf_request` is quite error prone:

- Positional `params` depend on the client because of the
  `offset_encoding`. Currently if there is one client using UTF-8 offset
  encoding and another using UTF-16, the positions in the request are
  wrong for one of the clients. To solve this the params would need to
  be created per client instead of once for all of them.

- `handler` is called *per* client but many users of it assume it is
  only called once.

  This can lead to a "select n + 1"
  kind of problem, where the handler makes another call to `buf_request`,
  multiplying the amount of requests.
  (There are in fact still some places where this happens in core)

  Or it leads to erratic behavior if called multiple times (E.g. the
  quicklist list flickering & being overwritten)
  (See hover or references implementation)

  `buf_request_all` returns an aggregate of the responses which is more
  sensible as it avoids this problem.

  For off-spec extensions it also has the problem that it sends requests to
  clients which cannot handle a given request.

Given that `buf_request` is in use by a lot of plugins this starts a
soft-phase out. Planned Steps:

- Remove from docs
- Provide an alternative, either `buf_request_all`, maybe with
  extensions (params being a function), or an entirely new method.
- Mark as deprecated in 0.9
- Remove in 0.10

To note:

- `buf_request_all` currently isn't ideal either because it suffers from
the `params` problem as well.

- This implies that the `vim.lsp.with` pattern will die, because the
  global handlers as they are don't fit a multi-client model, as most of
  the time an aggregate is needed.

1 files changed, 3 insertions, 2 deletions

diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua
index 8d4f388e23..fd64c1a495 100644
--- a/runtime/lua/vim/lsp.lua
+++ b/runtime/lua/vim/lsp.lua
@@ -1845,13 +1845,14 @@ api.nvim_create_autocmd('VimLeavePre', {
   end,
 })
 
+---@private
 --- Sends an async request for all active clients attached to the
 --- buffer.
 ---
 ---@param bufnr (number) Buffer handle, or 0 for current.
 ---@param method (string) LSP method name
----@param params (optional, table) Parameters to send to the server
----@param handler (optional, function) See |lsp-handler|
+---@param params table|nil Parameters to send to the server
+---@param handler function|nil See |lsp-handler|
 ---       If nil, follows resolution strategy defined in |lsp-handler-configuration|
 ---
 ---@returns 2-tuple: