This fixes the handler signature and also prevents n+1 requests firing
if there are multiple clients.

(The first `prepareCallHierarchy` handler is called once per client,
each invocation used `buf_request` to make more requests using *all*
clients)

Previously, the handler signature was:

  function(err, method, params, client_id, bufnr, config)

In order to better support external plugins that wish to extend the
protocol, there is other information which would be advantageous to
forward to the client, such as the original params of the request that
generated the callback.

In order to do this, we would need to break symmetry of the handlers, to
add an additional "params" as the 7th argument.

Instead, this PR changes the signature of the handlers to:

  function(err, result, ctx, config)

where ctx (the context) includes params, client_id, and bufnr. This also leaves
flexibility for future use-cases.

BREAKING_CHANGE: changes the signature of the built-in client handlers, requiring
updating handler calls

The official developer documentation in in :h dev-lua-doc specifies to
use "--@" for special/magic tokens. However, this format is not
consistent with EmmyLua notation (used by some Lua language servers) nor
with the C version of the magic docstring tokens which use three comment
characters.

Further, the code base is currently split between usage of "--@",
"---@", and "--- @". In an effort to remain consistent, change all Lua
magic tokens to use "---@" and update the developer documentation
accordingly.

ipairs terminates on the first nil index when iterating over table keys:

for i,k in ipairs( {[1] = 'test', [3] = 'test'} ) do
  print(i, k)
end

prints:
1 test

Instead, use pairs which continues iterating over the entire table:

for i,k in pairs( {[1] = 'test', [3] = 'test'} ) do
  print(i, k)
end

prints:
1 test
3 test

Given that the input is pre-filled with a path, it should be possible to
use dir completion.

Add the buffer number to the `textDocument/formatting` request, so
that it is passed to the handler.
The built-in formatting handlers do not use the buffer number, but user
overrides should have access to it.