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