fix(lsp): fix incorrect typing and doc for vim.lsp.rpc

Typings introduced in neovim#26032 and neovim#26552 have a few conflicts, so we
merge and clean them up. We also fix some incorrect type annotation in
the `vim.lsp.rpc` package. See the associated PR for more details.

Summary:

- vim.rpc.Dispatchers -> vim.lsp.rpc.Dispatchers
- vim.lsp.rpc.Error -> lsp.ResponseError
- Revise docs

runtime/doc/lsp.txt

@@ -2089,31 +2089,33 @@ Lua module: vim.lsp.rpc                                              *lsp-rpc*
 
 connect({host}, {port})                                *vim.lsp.rpc.connect()*
     Create a LSP RPC client factory that connects via TCP to the given host
-    and port
+    and port.
+
+    Return a function that can be passed to the `cmd` field for
+    |vim.lsp.start_client()| or |vim.lsp.start()|.
 
     Parameters: ~
       • {host}  (`string`) host to connect to
       • {port}  (`integer`) port to connect to
 
     Return: ~
         (`fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient`)
-        function intended to be passed to |vim.lsp.start_client()| or
-        |vim.lsp.start()| on the field cmd
 
                                          *vim.lsp.rpc.domain_socket_connect()*
 domain_socket_connect({pipe_path})
     Create a LSP RPC client factory that connects via named pipes (Windows) or
     unix domain sockets (Unix) to the given pipe_path (file path on Unix and
-    name on Windows)
+    name on Windows).
+
+    Return a function that can be passed to the `cmd` field for
+    |vim.lsp.start_client()| or |vim.lsp.start()|.
 
     Parameters: ~
       • {pipe_path}  (`string`) file path of the domain socket (Unix) or name
                      of the named pipe (Windows) to connect to
 
     Return: ~
         (`fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient`)
-        function intended to be passed to |vim.lsp.start_client()| or
-        |vim.lsp.start()| on the field cmd
 
 format_rpc_error({err})                       *vim.lsp.rpc.format_rpc_error()*
     Constructs an error message from an LSP error object.
@@ -2122,7 +2124,7 @@ format_rpc_error({err})                       *vim.lsp.rpc.format_rpc_error()*
       • {err}  (`table`) The error object
 
     Return: ~
-        (`string`) The formatted error message
+        (`string`) error_message The formatted error message
 
 notify({method}, {params})                              *vim.lsp.rpc.notify()*
     Sends a notification to the LSP server.
@@ -2144,24 +2146,29 @@ request({method}, {params}, {callback}, {notify_reply_callback})
                                  method
       • {callback}               (`fun(err: lsp.ResponseError?, result: any)`)
                                  Callback to invoke
-      • {notify_reply_callback}  (`function?`) Callback to invoke as soon as a
-                                 request is no longer pending
+      • {notify_reply_callback}  (`fun(message_id: integer)?`) Callback to
+                                 invoke as soon as a request is no longer
+                                 pending
 
-    Return: ~
-        (`boolean success, integer? request_id`) true, message_id if request
-        could be sent, `false` if not
+    Return (multiple): ~
+        (`boolean`) success `true` if request could be sent, `false` if not
+        (`integer?`) message_id if request could be sent, `nil` if not
 
                                             *vim.lsp.rpc.rpc_response_error()*
 rpc_response_error({code}, {message}, {data})
-    Creates an RPC response object/table.
+    Creates an RPC response table `error` to be sent to the LSP response.
 
     Parameters: ~
-      • {code}     (`integer`) RPC error code defined by JSON RPC
+      • {code}     (`integer`) RPC error code defined, see
+                   `vim.lsp.protocol.ErrorCodes`
       • {message}  (`string?`) arbitrary message to send to server
       • {data}     (`any?`) arbitrary data to send to server
 
     Return: ~
-        (`vim.lsp.rpc.Error`)
+        (`lsp.ResponseError`)
+
+    See also: ~
+      • lsp.ErrorCodes See `vim.lsp.protocol.ErrorCodes`
 
                                                          *vim.lsp.rpc.start()*
 start({cmd}, {cmd_args}, {dispatchers}, {extra_spawn_params})
@@ -2174,14 +2181,14 @@ start({cmd}, {cmd_args}, {dispatchers}, {extra_spawn_params})
       • {cmd}                 (`string`) Command to start the LSP server.
       • {cmd_args}            (`string[]`) List of additional string arguments
                               to pass to {cmd}.
-      • {dispatchers}         (`table?`) Dispatchers for LSP message types.
-                              Valid dispatcher names are:
+      • {dispatchers}         (`vim.lsp.rpc.Dispatchers?`) Dispatchers for LSP
+                              message types. Valid dispatcher names are:
                               • `"notification"`
                               • `"server_request"`
                               • `"on_error"`
                               • `"on_exit"`
-      • {extra_spawn_params}  (`table?`) Additional context for the LSP server
-                              process. May contain:
+      • {extra_spawn_params}  (`vim.lsp.rpc.ExtraSpawnParams?`) Additional
+                              context for the LSP server process. May contain:
                               • {cwd} (string) Working directory for the LSP
                                 server process
                               • {detached?} (boolean) Detach the LSP server
@@ -2191,7 +2198,7 @@ start({cmd}, {cmd_args}, {dispatchers}, {extra_spawn_params})
                                 variables for LSP server process
 
     Return: ~
-        (`table?`) client RPC object, with these methods:
+        (`vim.lsp.rpc.PublicClient?`) Client RPC object, with these methods:
         • `notify()` |vim.lsp.rpc.notify()|
         • `request()` |vim.lsp.rpc.request()|
         • `is_closing()` returns a boolean indicating if the RPC is closing.

runtime/lua/vim/_system.lua

@@ -61,7 +61,7 @@ end
 --- @field wait fun(self: vim.SystemObj, timeout?: integer): vim.SystemCompleted
 --- @field kill fun(self: vim.SystemObj, signal: integer|string)
 --- @field write fun(self: vim.SystemObj, data?: string|string[])
---- @field is_closing fun(self: vim.SystemObj): boolean?
+--- @field is_closing fun(self: vim.SystemObj): boolean
 local SystemObj = {}
 
 --- @param state vim.SystemState
@@ -140,7 +140,7 @@ end
 --- @return boolean
 function SystemObj:is_closing()
   local handle = self._state.handle
-  return handle == nil or handle:is_closing()
+  return handle == nil or handle:is_closing() or false
 end
 
 ---@param output fun(err:string?, data: string?)|false

runtime/lua/vim/lsp.lua

@@ -258,7 +258,7 @@ end
 --- Validates a client configuration as given to |vim.lsp.start_client()|.
 ---
 ---@param config (lsp.ClientConfig)
----@return (string|fun(dispatchers:vim.rpc.Dispatchers):RpcClientPublic?) Command
+---@return (string|fun(dispatchers:vim.rpc.Dispatchers):vim.lsp.rpc.PublicClient?) Command
 ---@return string[] Arguments
 ---@return string Encoding.
 local function validate_client_config(config)
@@ -291,7 +291,7 @@ local function validate_client_config(config)
     'flags.debounce_text_changes must be a number with the debounce time in milliseconds'
   )
 
-  local cmd, cmd_args --- @type (string|fun(dispatchers:vim.rpc.Dispatchers):RpcClientPublic), string[]
+  local cmd, cmd_args --- @type (string|fun(dispatchers:vim.rpc.Dispatchers):vim.lsp.rpc.PublicClient), string[]
   local config_cmd = config.cmd
   if type(config_cmd) == 'function' then
     cmd = config_cmd
@@ -826,6 +826,8 @@ function lsp.start_client(config)
   ---
   ---@param method (string) LSP method name
   ---@param params (table) The parameters for that method
+  ---@return any result
+  ---@return lsp.ResponseError error code and message set in case an exception happens during the request.
   function dispatch.server_request(method, params)
     if log.trace() then
       log.trace('server_request', method, params)
@@ -953,7 +955,7 @@ function lsp.start_client(config)
   end
 
   -- Start the RPC client.
-  local rpc --- @type RpcClientPublic?
+  local rpc --- @type vim.lsp.rpc.PublicClient?
   if type(cmd) == 'function' then
     rpc = cmd(dispatch)
   else