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.