feat(lsp): deprecate vim.lsp.stop_client (#36459)

* feat(lsp): deprecate `vim.lsp.stop_client`

* fix(tests): fix nil variable in diagnostic_spec.lua

runtime/doc/deprecated.txt

@@ -41,6 +41,7 @@ LSP
 • *vim.lsp.get_log_path()*		Use `vim.lsp.log.get_filename()` instead
 • *vim.lsp.get_buffers_by_client_id*	Use `vim.lsp.get_client_by_id(id).attached_buffers`
 					instead
+• *vim.lsp.stop_client()*		Use |Client:stop()| instead
 
 LUA
 

runtime/doc/lsp.txt

@@ -262,7 +262,7 @@ FAQ                                                     *lsp-faq*
 
 - Q: How to force-reload LSP?
 - A: Stop all clients, then reload the buffer. >vim
-     :lua vim.lsp.stop_client(vim.lsp.get_clients())
+     :lua vim.iter(vim.lsp.get_clients()):each(function(client) client:stop() end)
      :edit
 
 - Q: Why isn't completion working?
@@ -1238,22 +1238,6 @@ status()                                                    *vim.lsp.status()*
     Return: ~
         (`string`)
 
-stop_client({client_id}, {force})                      *vim.lsp.stop_client()*
-    Stops a client(s).
-
-    You can also use the `stop()` function on a |vim.lsp.Client| object. To
-    stop all clients: >lua
-        vim.lsp.stop_client(vim.lsp.get_clients())
-<
-
-    By default asks the server to shutdown, unless stop was requested already
-    for this client, then force-shutdown is attempted.
-
-    Parameters: ~
-      • {client_id}  (`integer|integer[]|vim.lsp.Client[]`) id, list of id's,
-                     or list of |vim.lsp.Client| objects
-      • {force}      (`boolean?`) shutdown forcefully
-
 tagfunc({pattern}, {flags})                                *vim.lsp.tagfunc()*
     Provides an interface between the built-in client and 'tagfunc'.
 

runtime/lua/vim/lsp.lua

@@ -1058,9 +1058,13 @@ end
 --- By default asks the server to shutdown, unless stop was requested
 --- already for this client, then force-shutdown is attempted.
 ---
+---@deprecated
 ---@param client_id integer|integer[]|vim.lsp.Client[] id, list of id's, or list of |vim.lsp.Client| objects
----@param force? boolean shutdown forcefully
+---@param force? boolean|integer Whether to shutdown forcefully.
+--- If `force` is a number, it will be treated as the time in milliseconds to
+--- wait before forcing the shutdown.
 function lsp.stop_client(client_id, force)
+  vim.deprecate('vim.lsp.stop_client()', 'vim.lsp.Client:stop()', '0.13')
   --- @type integer[]|vim.lsp.Client[]
   local ids = type(client_id) == 'table' and client_id or { client_id }
   for _, id in ipairs(ids) do

test/functional/plugin/lsp/diagnostic_spec.lua

@@ -129,7 +129,7 @@ describe('vim.lsp.diagnostic', function()
         }, { client_id = client_id })
 
         local diags = vim.diagnostic.get(diagnostic_bufnr)
-        vim.lsp.stop_client(client_id)
+        vim.lsp.get_client_by_id(client_id):stop()
         vim.api.nvim_exec_autocmds('VimLeavePre', { modeline = false })
         return diags
       end)
@@ -361,7 +361,7 @@ describe('vim.lsp.diagnostic', function()
       )
 
       exec_lua(function()
-        vim.lsp.stop_client(client_id)
+        vim.lsp.get_client_by_id(client_id):stop()
       end)
 
       eq(
@@ -373,9 +373,8 @@ describe('vim.lsp.diagnostic', function()
     end)
 
     it('keeps diagnostics when one client detaches and others still are attached', function()
-      local client_id2
       exec_lua(function()
-        client_id2 = vim.lsp.start({ name = 'dummy2', cmd = _G.server.cmd })
+        _G.client_id2 = vim.lsp.start({ name = 'dummy2', cmd = _G.server.cmd })
 
         vim.lsp.diagnostic.on_diagnostic(nil, {
           kind = 'full',
@@ -400,7 +399,7 @@ describe('vim.lsp.diagnostic', function()
       )
 
       exec_lua(function()
-        vim.lsp.stop_client(client_id2)
+        vim.lsp.get_client_by_id(_G.client_id2):stop()
       end)
 
       eq(

test/functional/plugin/lsp/document_color_spec.lua

@@ -109,7 +109,7 @@ body {
 
   it('clears document colors when sole client detaches', function()
     exec_lua(function()
-      vim.lsp.stop_client(client_id)
+      vim.lsp.get_client_by_id(client_id):stop()
     end)
 
     screen:expect({ grid = grid_without_colors })
@@ -176,7 +176,7 @@ body {
     end)
 
     exec_lua(function()
-      vim.lsp.stop_client(client_id2)
+      vim.lsp.get_client_by_id(client_id2):stop()
     end)
 
     screen:expect({ grid = grid_with_colors, unchanged = true })
@@ -192,7 +192,7 @@ body {
       )
 
       exec_lua(function()
-        vim.lsp.stop_client(client_id)
+        vim.lsp.get_client_by_id(client_id):stop()
       end)
 
       eq(

test/functional/plugin/lsp/inlay_hint_spec.lua

@@ -116,7 +116,7 @@ int main() {
 
   it('clears inlay hints when sole client detaches', function()
     exec_lua(function()
-      vim.lsp.stop_client(client_id)
+      vim.lsp.get_client_by_id(client_id):stop()
     end)
     screen:expect({ grid = grid_without_inlay_hints, unchanged = true })
   end)
@@ -139,7 +139,7 @@ int main() {
     end)
 
     exec_lua(function()
-      vim.lsp.stop_client(client_id2)
+      vim.lsp.get_client_by_id(client_id2):stop()
     end)
     screen:expect({ grid = grid_with_inlay_hints, unchanged = true })
   end)
@@ -422,7 +422,7 @@ test text
     exec_lua([[vim.lsp.inlay_hint.enable(true, { bufnr = bufnr })]])
     screen:expect({ grid = grid_with_inlay_hints })
     exec_lua(function()
-      vim.lsp.stop_client(client_id)
+      vim.lsp.get_client_by_id(client_id):stop()
     end)
     screen:expect({ grid = grid_without_inlay_hints, unchanged = true })
   end)

test/functional/plugin/lsp_spec.lua

@@ -77,7 +77,7 @@ describe('LSP', function()
 
   after_each(function()
     stop()
-    exec_lua('lsp.stop_client(lsp.get_clients(), true)')
+    exec_lua('vim.iter(lsp.get_clients()):each(function(client) client:stop(true) end)')
     api.nvim_exec_autocmds('VimLeavePre', { modeline = false })
   end)
 
@@ -116,7 +116,7 @@ describe('LSP', function()
       end)
     end)
 
-    it('start_client(), stop_client()', function()
+    it('start_client(), Client:stop()', function()
       retry(nil, 4000, function()
         eq(
           1,
@@ -179,34 +179,8 @@ describe('LSP', function()
       )
 
       exec_lua(function()
-        vim.lsp.stop_client({ _G.TEST_CLIENT2, _G.TEST_CLIENT3 })
+        vim.lsp.get_client_by_id(_G.TEST_CLIENT2):stop()
-      end)
+        vim.lsp.get_client_by_id(_G.TEST_CLIENT3):stop()
-      retry(nil, 4000, function()
-        eq(
-          0,
-          exec_lua(function()
-            return #vim.lsp.get_clients()
-          end)
-        )
-      end)
-    end)
-
-    it('stop_client() also works on client objects', function()
-      exec_lua(function()
-        _G.TEST_CLIENT2 = _G.test__start_client()
-        _G.TEST_CLIENT3 = _G.test__start_client()
-      end)
-      retry(nil, 4000, function()
-        eq(
-          3,
-          exec_lua(function()
-            return #vim.lsp.get_clients()
-          end)
-        )
-      end)
-      -- Stop all clients.
-      exec_lua(function()
-        vim.lsp.stop_client(vim.lsp.get_clients())
       end)
       retry(nil, 4000, function()
         eq(
@@ -844,7 +818,7 @@ describe('LSP', function()
         local client_id = assert(vim.lsp.start({ name = 'dummy', cmd = server.cmd }))
         local buf = vim.api.nvim_get_current_buf()
         vim.api.nvim_exec_autocmds('BufWritePre', { buffer = buf, modeline = false })
-        vim.lsp.stop_client(client_id)
+        vim.lsp.get_client_by_id(client_id):stop()
         return server.messages
       end)
       eq(4, #messages)
@@ -880,7 +854,7 @@ describe('LSP', function()
         local buf = vim.api.nvim_get_current_buf()
         local client_id = assert(vim.lsp.start({ name = 'dummy', cmd = server.cmd }))
         vim.api.nvim_exec_autocmds('BufWritePre', { buffer = buf, modeline = false })
-        vim.lsp.stop_client(client_id)
+        vim.lsp.get_client_by_id(client_id):stop()
         return {
           messages = server.messages,
           lines = vim.api.nvim_buf_get_lines(buf, 0, -1, true),
@@ -1320,7 +1294,7 @@ describe('LSP', function()
         assert(ok)
 
         local has_pending = client.requests[request_id] ~= nil
-        vim.lsp.stop_client(client_id)
+        vim.lsp.get_client_by_id(client_id):stop()
 
         return has_pending
       end)
@@ -3574,7 +3548,7 @@ describe('LSP', function()
           method = 'window/showDocument',
         }
         vim.lsp.handlers['window/showDocument'](nil, result, ctx)
-        vim.lsp.stop_client(client_id)
+        vim.lsp.get_client_by_id(client_id):stop()
         return {
           cursor = vim.api.nvim_win_get_cursor(0),
         }
@@ -4820,7 +4794,7 @@ describe('LSP', function()
         }))
 
         vim.lsp.buf.code_action({ apply = true })
-        vim.lsp.stop_client(client_id)
+        vim.lsp.get_client_by_id(client_id):stop()
         return server.messages
       end)
       eq('codeAction/resolve', result[4].method)
@@ -4864,7 +4838,7 @@ describe('LSP', function()
         }))
 
         vim.lsp.buf.code_action({ apply = true })
-        vim.lsp.stop_client(client_id)
+        vim.lsp.get_client_by_id(client_id):stop()
         return server.messages
       end)
       eq('codeAction/resolve', result[4].method)
@@ -4923,7 +4897,7 @@ describe('LSP', function()
         end
 
         vim.lsp.buf.code_action({ apply = true })
-        vim.lsp.stop_client(client_id)
+        vim.lsp.get_client_by_id(client_id):stop()
         return server.messages
       end)
       eq(
@@ -5386,7 +5360,7 @@ describe('LSP', function()
         vim.cmd.normal('v')
         vim.api.nvim_win_set_cursor(0, { 2, 3 })
         vim.lsp.buf.format({ bufnr = bufnr, false })
-        vim.lsp.stop_client(client_id)
+        vim.lsp.get_client_by_id(client_id):stop()
         return server.messages
       end)
       eq('textDocument/rangeFormatting', result[3].method)
@@ -5423,7 +5397,7 @@ describe('LSP', function()
         vim.api.nvim_win_set_cursor(0, { 1, 2 })
         vim.lsp.buf.format({ bufnr = bufnr, false })
 
-        vim.lsp.stop_client(client_id)
+        vim.lsp.get_client_by_id(client_id):stop()
         return server.messages
       end)
       local expected_methods = {
@@ -5558,7 +5532,7 @@ describe('LSP', function()
       n.feed(':=vim.lsp.buf.definition({ reuse_win = true })<CR>')
       eq(result.win, api.nvim_get_current_win())
       exec_lua(function()
-        vim.lsp.stop_client(result.client_id)
+        vim.lsp.get_client_by_id(result.client_id):stop()
       end)
     end)
     it('merges results from multiple servers', function()
@@ -5597,8 +5571,8 @@ describe('LSP', function()
             response = r
           end,
         })
-        vim.lsp.stop_client(client_id1)
+        vim.lsp.get_client_by_id(client_id1):stop()
-        vim.lsp.stop_client(client_id2)
+        vim.lsp.get_client_by_id(client_id2):stop()
         return response
       end)
       eq(2, #result.items)
@@ -5662,7 +5636,7 @@ describe('LSP', function()
 
     after_each(function()
       exec_lua(function()
-        vim.lsp.stop_client(_G.client_id)
+        vim.lsp.get_client_by_id(_G.client_id):stop()
       end)
     end)
 
@@ -6071,7 +6045,7 @@ describe('LSP', function()
 
             wait_for_message()
 
-            vim.lsp.stop_client(client_id)
+            vim.lsp.get_client_by_id(client_id):stop()
 
             return server.messages
           end)
@@ -6518,7 +6492,7 @@ describe('LSP', function()
             },
           }, { client_id = client_id })
 
-          vim.lsp.stop_client(client_id, true)
+          vim.lsp.get_client_by_id(client_id):stop(true)
           return _G.watching
         end)
       end