feat(lsp)!: change handler signature

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

1 files changed, 23 insertions, 15 deletions

diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index b04d9c267a..f78d152663 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -202,23 +202,28 @@ responses and notifications from LSP servers.
 
 For |lsp-request|, each |lsp-handler| has this signature: >
 
-  function(err, method, result, client_id, bufnr, config)
+  function(err, result, ctx, config)
 <
         Parameters: ~
             {err}       (table|nil)
                             When the language server is unable to complete a
                             request, a table with information about the error
                             is sent. Otherwise, it is `nil`. See |lsp-response|.
-            {method}    (string)
-                            The |lsp-method| name.
             {result}    (Result | Params | nil)
                             When the language server is able to succesfully
                             complete a request, this contains the `result` key
                             of the response. See |lsp-response|.
-            {client_id} (number)
-                            The ID of the |vim.lsp.client|.
-            {bufnr}     (Buffer)
-                            Buffer handle, or 0 for current.
+            {ctx}       (table)
+                            Context describes additional calling state
+                            associated with the handler. It consists of the
+                            following key, value pairs:
+
+                            {method}    (string)
+                                            The |lsp-method| name.
+                            {client_id} (number)
+                                            The ID of the |vim.lsp.client|.
+                            {bufnr}     (Buffer)
+                                           Buffer handle, or 0 for current.
             {config}    (table)
                             Configuration for the handler.
 
@@ -238,21 +243,24 @@ For |lsp-request|, each |lsp-handler| has this signature: >
 
 For |lsp-notification|, each |lsp-handler| has this signature: >
 
-  function(err, method, params, client_id, bufnr, config)
+  function(err, result, ctx, config)
 <
         Parameters: ~
             {err}       (nil)
                             This is always `nil`.
                             See |lsp-notification|
-            {method}    (string)
-                            The |lsp-method| name.
-            {params}    (Params)
+            {result}    (Result)
                             This contains the `params` key of the notification.
                             See |lsp-notification|
-            {client_id} (number)
-                            The ID of the |vim.lsp.client|
-            {bufnr}     (nil)
-                            `nil`, as the server doesn't have an associated buffer.
+            {ctx}       (table)
+                            Context describes additional calling state
+                            associated with the handler. It consists of the
+                            following key, value pairs:
+
+                            {method}    (string)
+                                            The |lsp-method| name.
+                            {client_id} (number)
+                                            The ID of the |vim.lsp.client|.
             {config}    (table)
                             Configuration for the handler.