Merge pull request #18507 from gpanders/au-lsp-attached

2 files changed, 50 insertions, 12 deletions

diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index 13644cf208..e328bd28b5 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -106,11 +106,13 @@ internally and are no longer exposed as part of the API. Instead, use
 *vim.lsp.diagnostic.set_underline()*
 *vim.lsp.diagnostic.set_virtual_text()*
 
-LSP Utility Functions ~
+LSP Functions ~
 
 *vim.lsp.util.diagnostics_to_items()*	Use |vim.diagnostic.toqflist()| instead.
 *vim.lsp.util.set_qflist()*		Use |setqflist()| instead.
 *vim.lsp.util.set_loclist()*		Use |setloclist()| instead.
+*vim.lsp.buf_get_clients()*		Use |vim.lsp.get_active_clients()| with
+                                        {buffer = bufnr} instead.
 
 Lua ~
 *vim.register_keystroke_callback()* Use |vim.on_key()| instead.
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 569c570624..af28405705 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -461,6 +461,39 @@ LspSignatureActiveParameter
 ==============================================================================
 EVENTS                                                            *lsp-events*
 
+                                                                   *LspAttach*
+After an LSP client attaches to a buffer. The |autocmd-pattern| is the
+name of the buffer. When used from Lua, the client ID is passed to the
+callback in the "data" table. Example: >
+
+    vim.api.nvim_create_autocmd("LspAttach", {
+      callback = function(args)
+        local bufnr = args.buf
+        local client = vim.lsp.get_client_by_id(args.data.client_id)
+        if client.server_capabilities.completionProvider then
+          vim.bo[bufnr].omnifunc = "v:lua.vim.lsp.omnifunc"
+        end
+        if client.server_capabilities.definitionProvider then
+          vim.bo[bufnr].tagfunc = "v:lua.vim.lsp.tagfunc"
+        end
+      end,
+    })
+<
+                                                                   *LspDetach*
+Just before an LSP client detaches from a buffer. The |autocmd-pattern| is the
+name of the buffer. When used from Lua, the client ID is passed to the
+callback in the "data" table. Example: >
+
+    vim.api.nvim_create_autocmd("LspDetach", {
+      callback = function(args)
+        local client = vim.lsp.get_client_by_id(args.data.client_id)
+        -- Do something with the client
+        vim.cmd("setlocal tagfunc< omnifunc<")
+      end,
+    })
+<
+In addition, the following |User| |autocommands| are provided:
+
 LspProgressUpdate                                          *LspProgressUpdate*
    Upon receipt of a progress notification from the server. See
    |vim.lsp.util.get_progress_messages()|.
@@ -498,14 +531,6 @@ buf_detach_client({bufnr}, {client_id})          *vim.lsp.buf_detach_client()*
                     {bufnr}      (number) Buffer handle, or 0 for current
                     {client_id}  (number) Client id
 
-buf_get_clients({bufnr})                           *vim.lsp.buf_get_clients()*
-                Gets a map of client_id:client pairs for the given buffer,
-                where each value is a |vim.lsp.client| object.
-
-                Parameters: ~
-                    {bufnr}  (optional, number): Buffer handle, or 0 for
-                             current
-
 buf_is_attached({bufnr}, {client_id})              *vim.lsp.buf_is_attached()*
                 Checks if a buffer is attached for a particular client.
 
@@ -696,11 +721,22 @@ formatexpr({opts})                                      *vim.lsp.formatexpr()*
                             • timeout_ms (default 500ms). The timeout period
                               for the formatting request.
 
-get_active_clients()                            *vim.lsp.get_active_clients()*
-                Gets all active clients.
+get_active_clients({filter})                    *vim.lsp.get_active_clients()*
+                Get active clients.
+
+                Parameters: ~
+                    {filter}  (table|nil) A table with key-value pairs used to
+                              filter the returned clients. The available keys
+                              are:
+                              • id (number): Only return clients with the
+                                given id
+                              • bufnr (number): Only return clients attached
+                                to this buffer
+                              • name (string): Only return clients with the
+                                given name
 
                 Return: ~
-                    Table of |vim.lsp.client| objects
+                    (table) List of |vim.lsp.client| objects
 
                                           *vim.lsp.get_buffers_by_client_id()*
 get_buffers_by_client_id({client_id})