gen_vimdoc.py: generate LSP docs

5 files changed, 990 insertions, 496 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 7d45330b66..f8fdd64a9b 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -569,7 +569,8 @@ nvim_call_atomic({calls})                                 *nvim_call_atomic()*
                     occurred, the values from all preceding calls will still
                     be returned.
 
-nvim_call_dict_function({dict}, {fn}, {args})      *nvim_call_dict_function()*
+                                                   *nvim_call_dict_function()*
+nvim_call_dict_function({dict}, {fn}, {args})
                 Calls a VimL |Dictionary-function| with the given arguments.
 
                 On execution error: fails with VimL error, does not update
@@ -1878,7 +1879,8 @@ nvim_buf_get_var({buffer}, {name})                        *nvim_buf_get_var()*
                 Return: ~
                     Variable value
 
-nvim_buf_get_virtual_text({buffer}, {lnum})      *nvim_buf_get_virtual_text()*
+                                                 *nvim_buf_get_virtual_text()*
+nvim_buf_get_virtual_text({buffer}, {lnum})
                 Get the virtual text (annotation) for a buffer line.
 
                 The virtual text is returned as list of lists, whereas the
@@ -2300,7 +2302,8 @@ nvim_tabpage_list_wins({tabpage})                   *nvim_tabpage_list_wins()*
                 Return: ~
                     List of windows in `tabpage`
 
-nvim_tabpage_set_var({tabpage}, {name}, {value})      *nvim_tabpage_set_var()*
+                                                      *nvim_tabpage_set_var()*
+nvim_tabpage_set_var({tabpage}, {name}, {value})
                 Sets a tab-scoped (t:) variable
 
                 Parameters: ~
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index d51c79318a..4d04e50998 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -49,8 +49,6 @@ go-to-definition, hover, etc.  Example config: >
   nnoremap <silent> 1gD   <cmd>lua vim.lsp.buf.type_definition()<CR>
   nnoremap <silent> gr    <cmd>lua vim.lsp.buf.references()<CR>
 
-<
-                                                        *vim.lsp.omnifunc()*
 Nvim provides the vim.lsp.omnifunc 'omnifunc' handler which allows
 |i_CTRL-X_CTRL-O| to consume LSP completion features. Example config (note the
 use of |v:lua| to call Lua from Vimscript): >
@@ -79,246 +77,24 @@ Some other plugin may be overriding the option. To avoid that, you could set
 the option in an |after-directory| ftplugin, e.g. "after/ftplugin/python.vim".
 
 ================================================================================
-                                                           *lsp-core-api*
+LSP API                                                 *lsp-api*
 
 The `vim.lsp` Lua module is a framework for building LSP plugins.
 
   1. Start with |vim.lsp.start_client()| and |vim.lsp.buf_attach_client()|.
   2. Peek at the API: >
      :lua print(vim.inspect(vim.lsp))
-<  3. See |lsp-advanced-js-example| for a full example.
-
-These are the core api functions for working with clients. You will mainly be
-using |vim.lsp.start_client()| and |vim.lsp.buf_attach_client()| for operations
-and |vim.lsp.get_client_by_id()| to retrieve a client by its id after it has
-initialized (or {config.on_init}. see below)
-
-                                                        *vim.lsp.start_client()*
-
-vim.lsp.start_client({config})
-
-  The main function used for starting clients.
-  Start a client and initialize it.
-
-  Its arguments are passed via a configuration object {config}.
- 
-  Mandatory parameters:~
- 
-  `root_dir`
-    {string} specifying the directory where the LSP server will base
-    as its rootUri on initialization.
- 
-  `cmd`
-    {string} or {list} which is the base command to execute for the LSP. A
-    string will be run using |'shell'| and a list will be interpreted as a
-    bare command with arguments passed. This is the same as |jobstart()|.
- 
-  Optional parameters:~
- 
-  `cmd_cwd`
-    {string} specifying the directory to launch the `cmd` process. This is not
-    related to `root_dir`.
-    By default, |getcwd()| is used.
- 
-  `cmd_env`
-    {table} specifying the environment flags to pass to the LSP on spawn.
-    This can be specified using keys like a map or as a list with `k=v` pairs
-    or both. Non-string values are coerced to a string.
-    For example:
-      `{ "PRODUCTION=true"; "TEST=123"; PORT = 8080; HOST = "0.0.0.0"; }`
- 
-  `capabilities`
-    A {table} which will be used instead of
-    `vim.lsp.protocol.make_client_capabilities()` which contains Nvim's
-    default capabilities and passed to the language server on initialization.
-    You'll probably want to use make_client_capabilities() and modify the
-    result.
-    NOTE:
-      To send an empty dictionary, you should use
-      `{[vim.type_idx]=vim.types.dictionary}` Otherwise, it will be encoded as
-      an array.
- 
-  `callbacks`
-    A {table} of whose keys are language server method names and the values
-    are `function(err, method, params, client_id)` See |lsp-callbacks| for
-    more. This will be combined with |lsp-default-callbacks| to resolve
-    the callbacks for a client as a fallback.
- 
-  `init_options`
-    A {table} of values to pass in the initialization request as
-    `initializationOptions`. See the `initialize` in the LSP spec.
- 
-  `name`
-    A {string} used in log messages. Defaults to {client_id}
- 
-  `offset_encoding`
-    One of "utf-8", "utf-16", or "utf-32" which is the encoding that the LSP
-    server expects.
-    The default encoding for Language Server Protocol is UTF-16, but there are
-    language servers which may use other encodings.
-    By default, it is "utf-16" as specified in the LSP specification. The
-    client does not verify this is correct.
- 
-  `on_error(code, ...)`
-    A function for handling errors thrown by client operation.  {code} is a
-    number describing the error. Other arguments may be passed depending on
-    the error kind. See |vim.lsp.client_errors| for possible errors.
-    `vim.lsp.client_errors[code]` can be used to retrieve a human
-    understandable string.
- 
-  `before_init(params, config)`
-    Callback invoked before the LSP "initialize" phase, where `params`
-    contains the parameters being sent to the server and `config` is the
-    config that was passed to `start_client()`. You can use this to modify
-    parameters before they are sent.
- 
-  `on_init(client, result)`
-    Callback invoked after the LSP "initialize" phase, where `result` is
-    a table of `capabilities` and anything else the server may send. For
-    example, clangd sends `initialize_result.offsetEncoding` if
-    `capabilities.offsetEncoding` was sent to it. You can only modify the
-    `client.offset_encoding` here before any notifications are sent.
- 
-  `on_attach(client, bufnr)`
-    A function which is called after the client is attached to a buffer.
- 
-  `on_exit(code, signal, client_id)`
-    A function which is called after the client has exited. code is the exit
-    code of the process, and signal is a number describing the signal used to
-    terminate (if any).
- 
-  `trace`
-     "off" | "messages" | "verbose" | nil passed directly to the language
-     server in the initialize request.
-     Invalid/empty values will default to "off"
- 
-  Returns:~
-    {client_id}
-    You can use |vim.lsp.get_client_by_id()| to get the actual client object.
-    See |lsp-client| for what the client structure will be.
- 
-  NOTE: The client is only available after it has been initialized, which
-  may happen after a small delay (or never if there is an error).  For this
-  reason, you may want to use `on_init` to do any actions once the client has
-  been initialized.
-
-The client object has some methods and members related to using the client.
-
-  Methods:~
-
-    `request(method, params, [callback])`
-      Send a request to the server. If callback is not specified, it will use
-      {client.callbacks} to try to find a callback. If one is not found there,
-      then an error will occur.
-      This is a thin wrapper around {client.rpc.request} with some additional
-      checking.
-      Returns a boolean to indicate if the notification was successful. If it
-      is false, then it will always be false (the client has shutdown).
-      If it was successful, then it will return the request id as the second
-      result. You can use this with `notify("$/cancel", { id = request_id })`
-      to cancel the request. This helper is made automatically with
-      |vim.lsp.buf_request()|
-      Returns: status, [client_id]
-
-    `notify(method, params)`
-      This is just {client.rpc.notify}()
-      Returns a boolean to indicate if the notification was successful. If it
-      is false, then it will always be false (the client has shutdown).
-      Returns: status
-
-    `cancel_request(id)`
-      This is just {client.rpc.notify}("$/cancelRequest", { id = id })
-      Returns the same as `notify()`.
-
-    `stop([force])`
-      Stop a client, optionally with force.
-      By default, it will just ask the server to shutdown without force.
-      If you request to stop a client which has previously been requested to
-      shutdown, it will automatically escalate and force shutdown.
-
-    `is_stopped()`
-      Returns true if the client is fully stopped.
-
-  Members: ~
-    `id` (number)
-      The id allocated to the client.
-
-    `name` (string)
-      If a name is specified on creation, that will be used. Otherwise it is
-      just the client id. This is used for logs and messages.
-
-    `offset_encoding` (string)
-      The encoding used for communicating with the server. You can modify this
-      in the `on_init` method before text is sent to the server.
-
-    `callbacks` (table)
-      The callbacks used by the client as described in |lsp-callbacks|.
-
-    `config` (table)
-      A copy of the table that was passed by the user to
-      |vim.lsp.start_client()|.
-
-    `server_capabilities` (table)
-      The response from the server sent on `initialize` describing the
-      server's capabilities.
-
-    `resolved_capabilities` (table)
-      A normalized table of capabilities that we have detected based on the
-      initialize response from the server in `server_capabilities`.
-
-
-                                                   *vim.lsp.buf_attach_client()*
-vim.lsp.buf_attach_client({bufnr}, {client_id})
-
-  Implements the `textDocument/did*` notifications required to track a buffer
-  for any language server.
-
-  Without calling this, the server won't be notified of changes to a buffer.
-
-                                                    *vim.lsp.get_client_by_id()*
-vim.lsp.get_client_by_id({client_id})
-
-  Look up an active client by its id, returns nil if it is not yet initialized
-  or is not a valid id. Returns |lsp-client|
-
-                                                         *vim.lsp.stop_client()*
-vim.lsp.stop_client({client_id}, [{force}])
-
-  Stop a client, optionally with force.
-  By default, it will just ask the server to shutdown without force.
-  If you request to stop a client which has previously been requested to
-  shutdown, it will automatically escalate and force shutdown.
-
-  You can also use `client.stop()` if you have access to the client.
-
-                                                    *vim.lsp.stop_all_clients()*
-vim.lsp.stop_all_clients([{force}])
-
-  |vim.lsp.stop_client()|, but for all active clients.
-
-                                                  *vim.lsp.get_active_clients()*
-vim.lsp.get_active_clients()
+<  3. See |lsp-extension-example| for a full example.
 
-  Return a list of all of the active clients. See |lsp-client| for a
-  description of what a client looks like.
+LSP core API is described at |lsp-core|.  Those are the core functions for
+creating and managing clients.
 
-                                                    *vim.lsp.rpc_response_error()*
-vim.lsp.rpc_response_error({code}, [{message}], [{data}])
+The `vim.lsp.buf_…` functions perform operations for all LSP clients attached
+to the given buffer. |lsp-buf|
 
-  Helper function to create an RPC response object/table. This is an alias for
-  |vim.lsp.rpc.rpc_response_error|. Code must be an RPC error code as
-  described in `vim.lsp.protocol.ErrorCodes`.
-
-  You can describe an optional {message} string or arbitrary {data} to send to
-  the server.
-
-================================================================================
-LSP CALLBACKS                                           *lsp-callbacks*
-
-DEFAULT CALLBACKS ~
-                                                   *vim.lsp.callbacks*
-The `vim.lsp.callbacks` table defines default callbacks used when
-creating a new client. Keys are LSP method names: >
+LSP request/response handlers are implemented as Lua callbacks.
+|lsp-callbacks| The `vim.lsp.callbacks` table defines default callbacks used
+when creating a new client. Keys are LSP method names: >
 
   :lua print(vim.inspect(vim.tbl_keys(vim.lsp.callbacks)))
 
@@ -330,7 +106,7 @@ These LSP requests/notifications are defined by default:
 
 You can check these via `vim.tbl_keys(vim.lsp.callbacks)`.
 
-These will be used preferrentially in `vim.lsp.buf` methods when handling
+These will be used preferentially in `vim.lsp.buf_…` methods for handling
 requests. They will also be used when responding to server requests and
 notifications.
 
@@ -369,117 +145,24 @@ Handlers are called for:
 - Handling requests initiated by the client if the request doesn't explicitly
   specify a callback (such as in |vim.lsp.buf_request|).
 
-================================================================================
+
 VIM.LSP.PROTOCOL                                              *vim.lsp.protocol*
 
 Module `vim.lsp.protocol` defines constants dictated by the LSP specification,
 and helper functions for creating protocol-related objects.
 https://github.com/microsoft/language-server-protocol/raw/gh-pages/_specifications/specification-3-14.md
 
-Useful examples are `vim.lsp.protocol.ErrorCodes`. These objects allow reverse
-lookup by either the number or string name.
-
-  e.g. vim.lsp.protocol.TextDocumentSyncKind.Full == 1
-       vim.lsp.protocol.TextDocumentSyncKind[1] == "Full"
-
-  Utility functions used internally are:
-    `vim.lsp.protocol.make_client_capabilities()`
-          Make a ClientCapabilities object. These are the builtin
-          capabilities.
-    `vim.lsp.protocol.resolve_capabilities(server_capabilites)`
-          Creates a normalized object describing capabilities from the server
-          capabilities.
-
-================================================================================
-                                                                  *vim.lsp.util*
-
-TODO: Describe the utils here for handling/applying things from LSP.
-
-================================================================================
-                                                               *lsp-buf-methods*
-
-The "vim.lsp.buf_" functions perform operations for all LSP clients attached
-to the given buffer.
-
-                                                         *vim.lsp.buf_request()*
-vim.lsp.buf_request({bufnr}, {method}, {params}, [{callback}])
-  Send a async request for all the clients active and attached to the buffer.
-
-  Parameters: ~
-    {bufnr}: The buffer handle or 0 for the current buffer.
-
-    {method}: The LSP method name.
-
-    {params}: The parameters to send.
-
-    {callback}: An optional `function(err, method, params, client_id)` which
-    will be called for this request. If you do not specify it, then it will
-    use the client's callback in {client.callbacks}. See |lsp-callbacks| for
-    more information.
-
-  Returns:~
-
-    A table from client id to the request id for all of the successful
-    requests.
-
-    The second result is a function which can be used to cancel all the
-    requests. You can do this individually with `client.cancel_request()`
-
-                                                    *vim.lsp.buf_request_sync()*
-vim.lsp.buf_request_sync({bufnr}, {method}, {params}, [{timeout_ms}])
-  Calls |vim.lsp.buf_request()|, but it will wait for the result and block Vim
-  in the process.
-  The parameters are the same as |vim.lsp.buf_request()|, but the return
-  result is different.
-  It will wait maximum of {timeout_ms} which defaults to 100ms.
-
-  Returns:~
-
-    If the timeout is exceeded or a cancel is sent or an error, it will cancel
-    the request and return `nil, err` where `err` is a string that describes
-    the reason why it failed.
-
-    If it is successful, it will return a table from client id to result id.
-
-                                                          *vim.lsp.buf_notify()*
-vim.lsp.buf_notify({bufnr}, {method}, {params})
-  Send a notification to all servers on the buffer.
-
-  Parameters: ~
-    {bufnr}: The buffer handle or 0 for the current buffer.
-
-    {method}: The LSP method name.
-
-    {params}: The parameters to send.
-
-================================================================================
-                                                                   *lsp-logging*
-
-                                                       *vim.lsp.set_log_level()*
-vim.lsp.set_log_level({level})
-  You can set the log level for language server client logging.
-  Possible values: "trace", "debug", "info", "warn", "error"
-
-  Default: "warn"
-
-  Example: `lua vim.lsp.set_log_level("debug")`
+For example `vim.lsp.protocol.ErrorCodes` allows reverse lookup by number or
+name: >
 
-                                                        *vim.lsp.get_log_path()*
-vim.lsp.get_log_path()
-  Returns the path that LSP logs are written.
-
-                                                            *vim.lsp.log_levels*
-vim.lsp.log_levels
-  Log level dictionary with reverse lookup as well.
- 
-  Can be used to lookup the number from the name or vice-versa.
-  Levels: "trace" (0), "debug" (1), "info" (2), "warn" (3), "error" (4)
+  vim.lsp.protocol.TextDocumentSyncKind.Full == 1
+  vim.lsp.protocol.TextDocumentSyncKind[1] == "Full"
 
 ================================================================================
-LSP EXAMPLE                                            *lsp-advanced-js-example*
+LSP EXAMPLE                                            *lsp-extension-example*
 
-This example is for plugin authors who want to work with "vim.lsp" framework.
-If you only want to use (not develop) LSP features, see |lsp-quickstart|.
+This example is for plugin authors or users who want a lot of control. If you
+are just getting started see |lsp-quickstart|.
 
 For more advanced configurations where just filtering by filetype isn't
 sufficient, you can use the `vim.lsp.start_client()` and
@@ -593,9 +276,724 @@ The example will:
 
 
 
-================================================================================
-LSP API                                                *lsp-api*
+==============================================================================
+Lua module: vim.lsp                                                 *lsp-core*
+
+buf_attach_client({bufnr}, {client_id})          *vim.lsp.buf_attach_client()*
+                Implements the `textDocument/did…` notifications required to
+                track a buffer for any language server.
+
+                Without calling this, the server won't be notified of changes
+                to a buffer.
+
+                Parameters: ~
+                    {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_get_full_text({bufnr})                       *vim.lsp.buf_get_full_text()*
+                TODO: Documentation
+
+buf_is_attached({bufnr}, {client_id})              *vim.lsp.buf_is_attached()*
+                Checks if a buffer is attached for a particular client.
+
+                Parameters: ~
+                    {bufnr}      (number) Buffer handle, or 0 for current
+                    {client_id}  (number) the client id
+
+buf_notify({bufnr}, {method}, {params})                 *vim.lsp.buf_notify()*
+                Sends a notification to all servers attached to the buffer.
+
+                Parameters: ~
+                    {bufnr}   (optional, number) Buffer handle, or 0 for
+                              current
+                    {method}  (string) LSP method name
+                    {params}  (string) Parameters to send to the server
+
+                Return: ~
+                    nil
+
+buf_print_debug_info({bufnr})                 *vim.lsp.buf_print_debug_info()*
+                TODO: Documentation
+
+                                                       *vim.lsp.buf_request()*
+buf_request({bufnr}, {method}, {params}, {callback})
+                Sends an async request for all active clients attached to the
+                buffer.
+
+                Parameters: ~
+                    {bufnr}     (number) Buffer handle, or 0 for current.
+                    {method}    (string) LSP method name
+                    {params}    (optional, table) Parameters to send to the
+                                server
+                    {callback}  (optional, functionnil) Handler
+
+                Return: ~
+                    2-tuple:
+                    • Map of client-id:request-id pairs for all successful
+                      requests.
+                    • Function which can be used to cancel all the requests.
+                      You could instead iterate all clients and call their
+                      `cancel_request()` methods.
+
+                                                  *vim.lsp.buf_request_sync()*
+buf_request_sync({bufnr}, {method}, {params}, {timeout_ms})
+                Sends a request to a server and waits for the response.
+
+                Calls |vim.lsp.buf_request()| but blocks Nvim while awaiting
+                the result. Parameters are the same as |vim.lsp.buf_request()|
+                but the return result is different. Wait maximum of
+                {timeout_ms} (default 100) ms.
+
+                Parameters: ~
+                    {bufnr}       (number) Buffer handle, or 0 for current.
+                    {method}      (string) LSP method name
+                    {params}      (optional, table) Parameters to send to the
+                                  server
+                    {timeout_ms}  (optional, number, default=100) Maximum time
+                                  in milliseconds to wait for a result.
+
+                Return: ~
+                    Map of client_id:request_result. On timeout, cancel or
+                    error, returns `(nil, err)` where `err` is a string
+                    describing the failure reason.
+
+cancel_request({id})                                *vim.lsp.cancel_request()*
+                TODO: Documentation
+
+client()                                                      *vim.lsp.client*
+                LSP client object.
+
+                • Methods:
+                  • request(method, params, [callback]) Send a request to the
+                    server. If callback is not specified, it will use
+                    {client.callbacks} to try to find a callback. If one is
+                    not found there, then an error will occur. This is a thin
+                    wrapper around {client.rpc.request} with some additional
+                    checking. Returns a boolean to indicate if the
+                    notification was successful. If it is false, then it will
+                    always be false (the client has shutdown). If it was
+                    successful, then it will return the request id as the
+                    second result. You can use this with `notify("$/cancel", {
+                    id = request_id })` to cancel the request. This helper is
+                    made automatically with |vim.lsp.buf_request()| Returns:
+                    status, [client_id]
+                  • notify(method, params) This is just {client.rpc.notify}()
+                    Returns a boolean to indicate if the notification was
+                    successful. If it is false, then it will always be false
+                    (the client has shutdown). Returns: status
+                  • cancel_request(id) This is just
+                    {client.rpc.notify}("$/cancelRequest", { id = id })
+                    Returns the same as `notify()` .
+                  • stop([force]) Stop a client, optionally with force. By
+                    default, it will just ask the server to shutdown without
+                    force. If you request to stop a client which has
+                    previously been requested to shutdown, it will
+                    automatically escalate and force shutdown.
+                  • is_stopped() Returns true if the client is fully stopped.
+
+                • Members
+                  • id (number): The id allocated to the client.
+                  • name (string): If a name is specified on creation, that
+                    will be used. Otherwise it is just the client id. This is
+                    used for logs and messages.
+                  • offset_encoding (string): The encoding used for
+                    communicating with the server. You can modify this in the
+                    `on_init` method before text is sent to the server.
+                  • callbacks (table): The callbacks used by the client as
+                    described in |lsp-callbacks|.
+                  • config (table): copy of the table that was passed by the
+                    user to |vim.lsp.start_client()|.
+                  • server_capabilities (table): Response from the server sent
+                    on `initialize` describing the server's capabilities.
+                  • resolved_capabilities (table): Normalized table of
+                    capabilities that we have detected based on the initialize
+                    response from the server in `server_capabilities` .
+
+client_is_stopped({client_id})                   *vim.lsp.client_is_stopped()*
+                TODO: Documentation
+
+err_message({...})                                     *vim.lsp.err_message()*
+                TODO: Documentation
+
+                                            *vim.lsp.for_each_buffer_client()*
+for_each_buffer_client({bufnr}, {callback})
+                TODO: Documentation
+
+get_active_clients()                            *vim.lsp.get_active_clients()*
+                Gets all active clients.
+
+                Return: ~
+                    Table of |vim.lsp.client| objects
+
+get_client_by_id({client_id})                     *vim.lsp.get_client_by_id()*
+                Gets an active client by id, or nil if the id is invalid or
+                the client is not yet initialized.
+
+                Parameters: ~
+                    {client_id}  client id number
+
+                Return: ~
+                    |vim.lsp.client| object, or nil
+
+get_log_path()                                        *vim.lsp.get_log_path()*
+                TODO: Documentation
+
+initialize()                                            *vim.lsp.initialize()*
+                TODO: Documentation
+
+is_dir({filename})                                          *vim.lsp.is_dir()*
+                TODO: Documentation
+
+is_stopped()                                            *vim.lsp.is_stopped()*
+                TODO: Documentation
+
+next_client_id()                                    *vim.lsp.next_client_id()*
+                TODO: Documentation
+
+notification({method}, {params})                      *vim.lsp.notification()*
+                TODO: Documentation
+
+notify({...})                                               *vim.lsp.notify()*
+                TODO: Documentation
+
+omnifunc({findstart}, {base})                             *vim.lsp.omnifunc()*
+                TODO: Documentation
+
+on_error({code}, {err})                                   *vim.lsp.on_error()*
+                TODO: Documentation
+
+on_exit({code}, {signal})                                  *vim.lsp.on_exit()*
+                TODO: Documentation
+
+once({fn})                                                    *vim.lsp.once()*
+                TODO: Documentation
+
+optional_validator({fn})                        *vim.lsp.optional_validator()*
+                TODO: Documentation
+
+print_debug_info()                                *vim.lsp.print_debug_info()*
+                TODO: Documentation
+
+request({method}, {params}, {callback})                    *vim.lsp.request()*
+                TODO: Documentation
+
+resolve_bufnr({bufnr})                               *vim.lsp.resolve_bufnr()*
+                TODO: Documentation
+
+resolve_callback({method})                        *vim.lsp.resolve_callback()*
+                TODO: Documentation
+
+server_request({method}, {params})                  *vim.lsp.server_request()*
+                TODO: Documentation
+
+set_log_level({level})                               *vim.lsp.set_log_level()*
+                Sets the global log level for LSP logging.
+
+                Levels by name: "trace", "debug", "info", "warn", "error"
+                Level numbers begin with "trace" at 0
+
+                Use `lsp.log_levels` for reverse lookup.
+
+                Parameters: ~
+                    {level}  [number|string] the case insensitive level name
+                             or number
+
+                See also: ~
+                    |vim.lsp.log_levels|
+
+start_client({config})                                *vim.lsp.start_client()*
+                Start a client and initialize it. Its arguments are passed via
+                a configuration object.
+
+                Mandatory parameters:
+
+                root_dir: {string} specifying the directory where the LSP
+                server will base as its rootUri on initialization.
+
+                cmd: {string} or {list} which is the base command to execute
+                for the LSP. A string will be run using 'shell' and a list
+                will be interpreted as a bare command with arguments passed.
+                This is the same as |jobstart()|.
+
+                Parameters: ~
+                    {cmd_cwd}          {string} specifying the directory to
+                                       launch the `cmd` process. This is not
+                                       related to `root_dir` . By default,
+                                       |getcwd()| is used.
+                    {cmd_env}          {table} specifying the environment
+                                       flags to pass to the LSP on spawn. This
+                                       can be specified using keys like a map
+                                       or as a list with `k=v` pairs or both.
+                                       Non-string values are coerced to a
+                                       string. For example: `{
+                                       "PRODUCTION=true"; "TEST=123"; PORT =
+                                       8080; HOST = "0.0.0.0"; }` .
+                    {capabilities}     Map overriding the default capabilities
+                                       defined by
+                                       |vim.lsp.protocol.make_client_capabilities()|,
+                                       passed to the language server on
+                                       initialization. Hint: use
+                                       make_client_capabilities() and modify
+                                       its result.
+                                       • Note: To send an empty dictionary use
+                                         `{[vim.type_idx]=vim.types.dictionary}`
+                                         , else it will be encoded as an
+                                         array.
+                    {callbacks}        Map of language server method names to `function(err, method, params,
+                                       client_id)` handler. Invoked for:
+                                       • Notifications from the server, where
+                                         `err` will always be `nil` .
+                                       • Requests initiated by the server. For
+                                         these you can respond by returning
+                                         two values: `result, err` where err
+                                         must be shaped like a RPC error, i.e.
+                                         `{ code, message, data? }` . Use
+                                         |vim.lsp.rpc_response_error()| to
+                                         help with this.
+                                       • Default callback for client requests
+                                         not explicitly specifying a callback.
+                    {init_options}     values to pass in the initialization
+                                       request as `initializationOptions` .
+                                       See `initialize` in the LSP spec.
+                    {name}             string used in log messages. Defaults
+                                       to {client_id}
+                    {offset_encoding}  One of "utf-8", "utf-16", or "utf-32"
+                                       which is the encoding that the LSP
+                                       server expects. By default, it is
+                                       "utf-16" as specified in the LSP
+                                       specification. The client does not
+                                       verify this is correct.
+                    {on_error}         Callback with parameters (code, ...),
+                                       invoked when the client operation
+                                       throws an error. {code} is a number
+                                       describing the error. Other arguments
+                                       may be passed depending on the error
+                                       kind. See |vim.lsp.client_errors| for
+                                       possible errors. Use
+                                       `vim.lsp.client_errors[code]` to get
+                                       human-friendly name.
+                    {before_init}      Callback with parameters
+                                       (initialize_params, config) invoked
+                                       before the LSP "initialize" phase,
+                                       where `params` contains the parameters
+                                       being sent to the server and `config`
+                                       is the config that was passed to
+                                       `start_client()` . You can use this to
+                                       modify parameters before they are sent.
+                    {on_init}          Callback (client, initialize_result)
+                                       invoked after LSP "initialize", where
+                                       `result` is a table of `capabilities`
+                                       and anything else the server may send.
+                                       For example, clangd sends
+                                       `initialize_result.offsetEncoding` if
+                                       `capabilities.offsetEncoding` was sent
+                                       to it. You can only modify the
+                                       `client.offset_encoding` here before
+                                       any notifications are sent.
+                    {on_exit}          Callback (code, signal, client_id)
+                                       invoked on client exit.
+                                       • code: exit code of the process
+                                       • signal: number describing the signal
+                                         used to terminate (if any)
+                                       • client_id: client handle
+                    {on_attach}        Callback (client, bufnr) invoked when
+                                       client attaches to a buffer.
+                    {trace}            "off" | "messages" | "verbose" | nil
+                                       passed directly to the language server
+                                       in the initialize request.
+                                       Invalid/empty values will default to
+                                       "off"
+
+                Return: ~
+                    Client id. |vim.lsp.get_client_by_id()| Note: client is
+                    only available after it has been initialized, which may
+                    happen after a small delay (or never if there is an
+                    error). Use `on_init` to do any actions once the client
+                    has been initialized.
+
+stop({force})                                                 *vim.lsp.stop()*
+                TODO: Documentation
+
+stop_all_clients({force})                         *vim.lsp.stop_all_clients()*
+                Stops all clients.
+
+                Parameters: ~
+                    {force}  boolean (optional) shutdown forcefully
+
+stop_client({client_id}, {force})                      *vim.lsp.stop_client()*
+                Stops a client.
+
+                You can also use the `stop()` function on a |vim.lsp.client|
+                object.
+
+                By default asks the server to shutdown, unless stop was
+                requested already for this client, then force-shutdown is
+                attempted.
+
+                Parameters: ~
+                    {client_id}  client id number
+                    {force}      boolean (optional) shutdown forcefully
+
+                                    *vim.lsp.text_document_did_open_handler()*
+text_document_did_open_handler({bufnr}, {client})
+                TODO: Documentation
+
+unsupported_method({method})                    *vim.lsp.unsupported_method()*
+                TODO: Documentation
+
+validate_client_config({config})            *vim.lsp.validate_client_config()*
+                TODO: Documentation
+
+validate_command({input})                         *vim.lsp.validate_command()*
+                TODO: Documentation
+
+validate_encoding({encoding})                    *vim.lsp.validate_encoding()*
+                TODO: Documentation
+
+
+==============================================================================
+Lua module: vim.lsp.protocol                                    *lsp-protocol*
+
+ifnil({a}, {b})                                     *vim.lsp.protocol.ifnil()*
+                TODO: Documentation
+
+                                 *vim.lsp.protocol.make_client_capabilities()*
+make_client_capabilities()
+                Gets a new ClientCapabilities object describing the LSP client
+                capabilities.
+
+                                     *vim.lsp.protocol.resolve_capabilities()*
+resolve_capabilities({server_capabilities})
+                `*` to match one or more characters in a path segment `?` to
+                match on one character in a path segment `**` to match any
+                number of path segments, including none `{}` to group
+                conditions (e.g. `**​/*.{ts,js}` matches all TypeScript and
+                JavaScript files) `[]` to declare a range of characters to
+                match in a path segment (e.g., `example.[0-9]` to match on
+                `example.0` , `example.1` , …) `[!...]` to negate a range of
+                characters to match in a path segment (e.g., `example.[!0-9]`
+                to match on `example.a` , `example.b` , but not `example.0` )
+
+                                *vim.lsp.protocol.transform_schema_comments()*
+transform_schema_comments()
+                TODO: Documentation
+
+                                *vim.lsp.protocol.transform_schema_to_table()*
+transform_schema_to_table()
+                TODO: Documentation
+
+
+==============================================================================
+Lua module: vim.lsp.buf                                              *lsp-buf*
+
+completion({context})                               *vim.lsp.buf.completion()*
+                TODO: Documentation
+
+declaration()                                      *vim.lsp.buf.declaration()*
+                TODO: Documentation
+
+definition()                                        *vim.lsp.buf.definition()*
+                TODO: Documentation
+
+formatting({options})                               *vim.lsp.buf.formatting()*
+                TODO: Documentation
+
+hover()                                                  *vim.lsp.buf.hover()*
+                TODO: Documentation
+
+implementation()                                *vim.lsp.buf.implementation()*
+                TODO: Documentation
+
+npcall({fn}, {...})                                     *vim.lsp.buf.npcall()*
+                TODO: Documentation
+
+ok_or_nil({status}, {...})                           *vim.lsp.buf.ok_or_nil()*
+                TODO: Documentation
+
+peek_definition()                              *vim.lsp.buf.peek_definition()*
+                TODO: Documentation
+
+                                              *vim.lsp.buf.range_formatting()*
+range_formatting({options}, {start_pos}, {end_pos})
+                TODO: Documentation
+
+references({context})                               *vim.lsp.buf.references()*
+                TODO: Documentation
+
+rename({new_name})                                      *vim.lsp.buf.rename()*
+                TODO: Documentation
+
+request({method}, {params}, {callback})                *vim.lsp.buf.request()*
+                TODO: Documentation
+
+signature_help()                                *vim.lsp.buf.signature_help()*
+                TODO: Documentation
+
+type_definition()                              *vim.lsp.buf.type_definition()*
+                TODO: Documentation
+
+
+==============================================================================
+Lua module: vim.lsp.callbacks                                  *lsp-callbacks*
+
+err_message({...})                           *vim.lsp.callbacks.err_message()*
+                TODO: Documentation
+
+                                       *vim.lsp.callbacks.location_callback()*
+location_callback({_}, {method}, {result})
+                TODO: Documentation
+
+                                             *vim.lsp.callbacks.log_message()*
+log_message({_}, {_}, {result}, {client_id})
+                TODO: Documentation
+
+                      *vim.lsp.callbacks.signature_help_to_preview_contents()*
+signature_help_to_preview_contents({input})
+                TODO: Documentation
+
+
+==============================================================================
+Lua module: vim.lsp.log                                              *lsp-log*
+
+get_filename()                                    *vim.lsp.log.get_filename()*
+                TODO: Documentation
+
+path_join({...})                                     *vim.lsp.log.path_join()*
+                TODO: Documentation
+
+set_level({level})                                   *vim.lsp.log.set_level()*
+                TODO: Documentation
+
+should_log({level})                                 *vim.lsp.log.should_log()*
+                TODO: Documentation
+
+
+==============================================================================
+Lua module: vim.lsp.rpc                                              *lsp-rpc*
+
+convert_NIL({v})                                   *vim.lsp.rpc.convert_NIL()*
+                TODO: Documentation
+
+                                       *vim.lsp.rpc.create_and_start_client()*
+create_and_start_client({cmd}, {cmd_args}, {handlers},
+                        {extra_spawn_params})
+                TODO: Documentation
+
+encode_and_send({payload})                     *vim.lsp.rpc.encode_and_send()*
+                TODO: Documentation
+
+force_env_list({final_env})                     *vim.lsp.rpc.force_env_list()*
+                TODO: Documentation
+
+                            *vim.lsp.rpc.format_message_with_content_length()*
+format_message_with_content_length({encoded_message})
+                TODO: Documentation
+
+format_rpc_error({err})                       *vim.lsp.rpc.format_rpc_error()*
+                TODO: Documentation
+
+handle_body({body})                                *vim.lsp.rpc.handle_body()*
+                TODO: Documentation
+
+is_dir({filename})                                      *vim.lsp.rpc.is_dir()*
+                TODO: Documentation
+
+json_decode({data})                                *vim.lsp.rpc.json_decode()*
+                TODO: Documentation
+
+json_encode({data})                                *vim.lsp.rpc.json_encode()*
+                TODO: Documentation
+
+notification({method}, {params})                  *vim.lsp.rpc.notification()*
+                TODO: Documentation
+
+on_error({errkind}, {...})                            *vim.lsp.rpc.on_error()*
+                TODO: Documentation
+
+on_exit({code}, {signal})                              *vim.lsp.rpc.on_exit()*
+                TODO: Documentation
+
+onexit({code}, {signal})                                *vim.lsp.rpc.onexit()*
+                TODO: Documentation
+
+parse_headers({header})                          *vim.lsp.rpc.parse_headers()*
+                TODO: Documentation
+
+                                                 *vim.lsp.rpc.pcall_handler()*
+pcall_handler({errkind}, {status}, {head}, {...})
+                TODO: Documentation
+
+request_parser_loop()                      *vim.lsp.rpc.request_parser_loop()*
+                TODO: Documentation
+
+                                            *vim.lsp.rpc.rpc_response_error()*
+rpc_response_error({code}, {message}, {data})
+                Creates an RPC response object/table.
+
+                Parameters: ~
+                    {code}     RPC error code defined in
+                               `vim.lsp.protocol.ErrorCodes`
+                    {message}  (optional) arbitrary message to send to server
+                    {data}     (optional) arbitrary data to send to server
+
+send_notification({method}, {params})        *vim.lsp.rpc.send_notification()*
+                TODO: Documentation
+
+                                                  *vim.lsp.rpc.send_request()*
+send_request({method}, {params}, {callback})
+                TODO: Documentation
+
+                                                 *vim.lsp.rpc.send_response()*
+send_response({request_id}, {err}, {result})
+                TODO: Documentation
+
+server_request({method}, {params})              *vim.lsp.rpc.server_request()*
+                TODO: Documentation
+
+try_call({errkind}, {fn}, {...})                      *vim.lsp.rpc.try_call()*
+                TODO: Documentation
+
+
+==============================================================================
+Lua module: vim.lsp.util                                            *lsp-util*
+
+                                     *vim.lsp.util.apply_text_document_edit()*
+apply_text_document_edit({text_document_edit})
+                TODO: Documentation
+
+                                             *vim.lsp.util.apply_text_edits()*
+apply_text_edits({text_edits}, {bufnr})
+                TODO: Documentation
+
+                                         *vim.lsp.util.apply_workspace_edit()*
+apply_workspace_edit({workspace_edit})
+                TODO: Documentation
+
+buf_clear_diagnostics({bufnr})          *vim.lsp.util.buf_clear_diagnostics()*
+                TODO: Documentation
+
+                               *vim.lsp.util.buf_diagnostics_save_positions()*
+buf_diagnostics_save_positions({bufnr}, {diagnostics})
+                TODO: Documentation
+
+                                    *vim.lsp.util.buf_diagnostics_underline()*
+buf_diagnostics_underline({bufnr}, {diagnostics})
+                TODO: Documentation
+
+                                 *vim.lsp.util.buf_diagnostics_virtual_text()*
+buf_diagnostics_virtual_text({bufnr}, {diagnostics})
+                TODO: Documentation
+
+character_offset({buf}, {row}, {col})        *vim.lsp.util.character_offset()*
+                TODO: Documentation
+
+                                        *vim.lsp.util.close_preview_autocmd()*
+close_preview_autocmd({events}, {winnr})
+                TODO: Documentation
+
+                              *vim.lsp.util.convert_input_to_markdown_lines()*
+convert_input_to_markdown_lines({input}, {contents})
+                TODO: Documentation
+
+                                     *vim.lsp.util.extract_completion_items()*
+extract_completion_items({result})
+                TODO: Documentation
+
+                                      *vim.lsp.util.fancy_floating_markdown()*
+fancy_floating_markdown({contents}, {opts})
+                TODO: Documentation
+
+find_window_by_var({name}, {value})        *vim.lsp.util.find_window_by_var()*
+                TODO: Documentation
+
+focusable_float({unique_name}, {fn})          *vim.lsp.util.focusable_float()*
+                TODO: Documentation
+
+                                            *vim.lsp.util.focusable_preview()*
+focusable_preview({unique_name}, {fn})
+                TODO: Documentation
+
+                                   *vim.lsp.util.get_current_line_to_cursor()*
+get_current_line_to_cursor()
+                TODO: Documentation
+
+                                  *vim.lsp.util.get_severity_highlight_name()*
+get_severity_highlight_name({severity})
+                TODO: Documentation
+
+                                              *vim.lsp.util.highlight_range()*
+highlight_range({bufnr}, {ns}, {hiname}, {start}, {finish})
+                TODO: Documentation
+
+                                             *vim.lsp.util.highlight_region()*
+highlight_region({ft}, {start}, {finish})
+                TODO: Documentation
+
+jump_to_location({location})                 *vim.lsp.util.jump_to_location()*
+                TODO: Documentation
+
+locations_to_items({locations})            *vim.lsp.util.locations_to_items()*
+                TODO: Documentation
+
+                                  *vim.lsp.util.make_floating_popup_options()*
+make_floating_popup_options({width}, {height}, {opts})
+                TODO: Documentation
+
+make_position_params()                   *vim.lsp.util.make_position_params()*
+                TODO: Documentation
+
+npcall({fn}, {...})                                    *vim.lsp.util.npcall()*
+                TODO: Documentation
+
+ok_or_nil({status}, {...})                          *vim.lsp.util.ok_or_nil()*
+                TODO: Documentation
+
+                                   *vim.lsp.util.open_floating_peek_preview()*
+open_floating_peek_preview({bufnr}, {start}, {finish}, {opts})
+                TODO: Documentation
+
+                                        *vim.lsp.util.open_floating_preview()*
+open_floating_preview({contents}, {filetype}, {opts})
+                TODO: Documentation
+
+set_lines({lines}, {A}, {B}, {new_lines})           *vim.lsp.util.set_lines()*
+                TODO: Documentation
+
+set_loclist({locations})                          *vim.lsp.util.set_loclist()*
+                TODO: Documentation
+
+set_qflist({locations})                            *vim.lsp.util.set_qflist()*
+                TODO: Documentation
+
+show_line_diagnostics()                 *vim.lsp.util.show_line_diagnostics()*
+                TODO: Documentation
+
+sort_by_key({fn})                                 *vim.lsp.util.sort_by_key()*
+                TODO: Documentation
+
+split_lines({value})                              *vim.lsp.util.split_lines()*
+                TODO: Documentation
+
+              *vim.lsp.util.text_document_completion_list_to_complete_items()*
+text_document_completion_list_to_complete_items({result})
+                TODO: Documentation
+
+trim_empty_lines({lines})                    *vim.lsp.util.trim_empty_lines()*
+                TODO: Documentation
 
+                                *vim.lsp.util.try_trim_markdown_code_blocks()*
+try_trim_markdown_code_blocks({lines})
+                TODO: Documentation
 
+validate_lsp_position({pos})            *vim.lsp.util.validate_lsp_position()*
+                TODO: Documentation
 
  vim:tw=78:ts=8:ft=help:norl:
diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua
index 0ecf57f50c..a14c432f0c 100644
--- a/runtime/lua/vim/lsp.lua
+++ b/runtime/lua/vim/lsp.lua
@@ -204,95 +204,155 @@ local function text_document_did_open_handler(bufnr, client)
   client.notify('textDocument/didOpen', params)
 end
 
+--- LSP client object.
+---
+--- - Methods:
+---
+---  - request(method, params, [callback])
+---     Send a request to the server. If callback is not specified, it will use
+---     {client.callbacks} to try to find a callback. If one is not found there,
+---     then an error will occur.
+---     This is a thin wrapper around {client.rpc.request} with some additional
+---     checking.
+---     Returns a boolean to indicate if the notification was successful. If it
+---     is false, then it will always be false (the client has shutdown).
+---     If it was successful, then it will return the request id as the second
+---     result. You can use this with `notify("$/cancel", { id = request_id })`
+---     to cancel the request. This helper is made automatically with
+---     |vim.lsp.buf_request()|
+---     Returns: status, [client_id]
+---
+---  - notify(method, params)
+---     This is just {client.rpc.notify}()
+---     Returns a boolean to indicate if the notification was successful. If it
+---     is false, then it will always be false (the client has shutdown).
+---     Returns: status
+---
+---  - cancel_request(id)
+---     This is just {client.rpc.notify}("$/cancelRequest", { id = id })
+---     Returns the same as `notify()`.
+---
+---  - stop([force])
+---     Stop a client, optionally with force.
+---     By default, it will just ask the server to shutdown without force.
+---     If you request to stop a client which has previously been requested to
+---     shutdown, it will automatically escalate and force shutdown.
+---
+---  - is_stopped()
+---     Returns true if the client is fully stopped.
+---
+--- - Members
+---  - id (number): The id allocated to the client.
+---
+---  - name (string): If a name is specified on creation, that will be
+---    used. Otherwise it is just the client id. This is used for
+---    logs and messages.
+---
+---  - offset_encoding (string): The encoding used for communicating
+---    with the server. You can modify this in the `on_init` method
+---    before text is sent to the server.
+---
+---  - callbacks (table): The callbacks used by the client as
+---    described in |lsp-callbacks|.
+---
+---  - config (table): copy of the table that was passed by the user
+---    to |vim.lsp.start_client()|.
+---
+---  - server_capabilities (table): Response from the server sent on
+---    `initialize` describing the server's capabilities.
+---
+---  - resolved_capabilities (table): Normalized table of
+---    capabilities that we have detected based on the initialize
+---    response from the server in `server_capabilities`.
+function lsp.client()
+  error()
+end
 
 --- Start a client and initialize it.
--- Its arguments are passed via a configuration object.
---
--- Mandatory parameters:
---
--- root_dir: {string} specifying the directory where the LSP server will base
--- as its rootUri on initialization.
---
--- cmd: {string} or {list} which is the base command to execute for the LSP. A
--- string will be run using |'shell'| and a list will be interpreted as a bare
--- command with arguments passed. This is the same as |jobstart()|.
---
--- Optional parameters:
-
--- cmd_cwd: {string} specifying the directory to launch the `cmd` process. This
--- is not related to `root_dir`. By default, |getcwd()| is used.
---
--- cmd_env: {table} specifying the environment flags to pass to the LSP on
--- spawn.  This can be specified using keys like a map or as a list with `k=v`
--- pairs or both. Non-string values are coerced to a string.
--- For example: `{ "PRODUCTION=true"; "TEST=123"; PORT = 8080; HOST = "0.0.0.0"; }`.
---
--- capabilities: A {table} which will be used instead of
--- `vim.lsp.protocol.make_client_capabilities()` which contains neovim's
--- default capabilities and passed to the language server on initialization.
--- You'll probably want to use make_client_capabilities() and modify the
--- result.
--- NOTE:
---   To send an empty dictionary, you should use
---   `{[vim.type_idx]=vim.types.dictionary}` Otherwise, it will be encoded as
---   an array.
---
--- callbacks: A {table} of whose keys are language server method names and the
--- values are `function(err, method, params, client_id)`.
--- This will be called for:
--- - notifications from the server, where `err` will always be `nil`
--- - requests initiated by the server. For these, you can respond by returning
--- two values: `result, err`. The err must be in the format of an RPC error,
--- which is `{ code, message, data? }`. You can use |vim.lsp.rpc_response_error()|
--- to help with this.
--- - as a callback for requests initiated by the client if the request doesn't
--- explicitly specify a callback.
---
--- init_options: A {table} of values to pass in the initialization request
--- as `initializationOptions`. See the `initialize` in the LSP spec.
---
--- name: A {string} used in log messages. Defaults to {client_id}
---
--- offset_encoding: One of 'utf-8', 'utf-16', or 'utf-32' which is the
--- encoding that the LSP server expects. By default, it is 'utf-16' as
--- specified in the LSP specification. The client does not verify this
--- is correct.
---
--- on_error(code, ...): A function for handling errors thrown by client
--- operation. {code} is a number describing the error. Other arguments may be
--- passed depending on the error kind.  @see |vim.lsp.client_errors| for
--- possible errors. `vim.lsp.client_errors[code]` can be used to retrieve a
--- human understandable string.
---
--- before_init(initialize_params, config): A function which is called *before*
--- the request `initialize` is completed. `initialize_params` contains
--- the parameters we are sending to the server and `config` is the config that
--- was passed to `start_client()` for convenience. You can use this to modify
--- parameters before they are sent.
---
--- on_init(client, initialize_result): A function which is called after the
--- request `initialize` is completed. `initialize_result` contains
--- `capabilities` and anything else the server may send. For example, `clangd`
--- sends `result.offsetEncoding` if `capabilities.offsetEncoding` was sent to
--- it.
---
--- on_exit(code, signal, client_id): A function which is called after the
--- client has exited. code is the exit code of the process, and signal is a
--- number describing the signal used to terminate (if any).
---
--- on_attach(client, bufnr): A function which is called after the client is
--- attached to a buffer.
---
--- trace:  'off' | 'messages' | 'verbose' | nil passed directly to the language
--- server in the initialize request. Invalid/empty values will default to 'off'
---
--- @returns client_id You can use |vim.lsp.get_client_by_id()| to get the
--- actual client.
---
--- NOTE: The client is only available *after* it has been initialized, which
--- may happen after a small delay (or never if there is an error).
--- For this reason, you may want to use `on_init` to do any actions once the
--- client has been initialized.
+--- Its arguments are passed via a configuration object.
+---
+--- Mandatory parameters:
+---
+--- root_dir: {string} specifying the directory where the LSP server will base
+--- as its rootUri on initialization.
+---
+--- cmd: {string} or {list} which is the base command to execute for the LSP. A
+--- string will be run using 'shell' and a list will be interpreted as a bare
+--- command with arguments passed. This is the same as |jobstart()|.
+---
+--@param cmd_cwd: {string} specifying the directory to launch the `cmd` process. This
+--- is not related to `root_dir`. By default, |getcwd()| is used.
+---
+--@param cmd_env: {table} specifying the environment flags to pass to the LSP on
+--- spawn.  This can be specified using keys like a map or as a list with `k=v`
+--- pairs or both. Non-string values are coerced to a string.
+--- For example: `{ "PRODUCTION=true"; "TEST=123"; PORT = 8080; HOST = "0.0.0.0"; }`.
+---
+--@param capabilities: Map overriding the default capabilities defined by
+--- |vim.lsp.protocol.make_client_capabilities()|, passed to the language
+--- server on initialization. Hint: use make_client_capabilities() and modify
+--- its result.
+--- - Note: To send an empty dictionary use
+---   `{[vim.type_idx]=vim.types.dictionary}`, else it will be encoded as an
+---   array.
+---
+--@param callbacks: Map of language server method names to
+--- `function(err, method, params, client_id)` handler.
+--- Invoked for:
+--- - Notifications from the server, where `err` will always be `nil`.
+--- - Requests initiated by the server. For these you can respond by returning
+---   two values: `result, err` where err must be shaped like a RPC error,
+---   i.e. `{ code, message, data? }`. Use |vim.lsp.rpc_response_error()| to
+---   help with this.
+--- - Default callback for client requests not explicitly specifying
+---   a callback.
+---
+--@param init_options values to pass in the initialization request
+--- as `initializationOptions`. See `initialize` in the LSP spec.
+---
+--@param name: string used in log messages. Defaults to {client_id}
+---
+--@param offset_encoding: One of "utf-8", "utf-16", or "utf-32" which is the
+--- encoding that the LSP server expects. By default, it is "utf-16" as
+--- specified in the LSP specification. The client does not verify this
+--- is correct.
+---
+--@param on_error Callback with parameters (code, ...), invoked
+--- when the client operation throws an error.
+--- {code} is a number describing the error. Other arguments may be
+--- passed depending on the error kind.  See |vim.lsp.client_errors| for
+--- possible errors. Use `vim.lsp.client_errors[code]` to get human-friendly
+--- name.
+---
+--@param before_init Callback with parameters (initialize_params, config) invoked
+--- before the LSP "initialize" phase, where `params` contains the
+--- parameters being sent to the server and `config` is the config
+--- that was passed to `start_client()`. You can use this to modify
+--- parameters before they are sent.
+---
+--@param on_init Callback (client, initialize_result) invoked after LSP
+--- "initialize", where `result` is a table of `capabilities` and
+--- anything else the server may send. For example, clangd sends
+--- `initialize_result.offsetEncoding` if `capabilities.offsetEncoding` was
+--- sent to it. You can only modify the `client.offset_encoding` here before
+--- any notifications are sent.
+---
+--@param on_exit Callback (code, signal, client_id) invoked on client
+--- exit.
+--- - code: exit code of the process
+--- - signal: number describing the signal used to terminate (if any)
+--- - client_id: client handle
+---
+--@param on_attach Callback (client, bufnr) invoked when client
+--- attaches to a buffer.
+---
+--@param trace:  "off" | "messages" | "verbose" | nil passed directly to the language
+--- server in the initialize request. Invalid/empty values will default to "off"
+---
+--@returns Client id. |vim.lsp.get_client_by_id()| Note: client is only
+--- available after it has been initialized, which may happen after a small
+--- delay (or never if there is an error). Use `on_init` to do any actions once
+--- the client has been initialized.
 function lsp.start_client(config)
   local cleaned_config = validate_client_config(config)
   local cmd, cmd_args, offset_encoding = cleaned_config.cmd, cleaned_config.cmd_args, cleaned_config.offset_encoding
@@ -402,8 +462,8 @@ function lsp.start_client(config)
       initializationOptions = config.init_options;
       -- The capabilities provided by the client (editor or tool)
       capabilities = config.capabilities or protocol.make_client_capabilities();
-      -- The initial trace setting. If omitted trace is disabled ('off').
-      -- trace = 'off' | 'messages' | 'verbose';
+      -- The initial trace setting. If omitted trace is disabled ("off").
+      -- trace = "off" | "messages" | "verbose";
       trace = valid_traces[config.trace] or 'off';
       -- The workspace folders configured in the client when the server starts.
       -- This property is only available if the client supports workspace folders.
@@ -634,10 +694,13 @@ function lsp._text_document_did_save_handler(bufnr)
   end)
 end
 
--- Implements the textDocument/did* notifications required to track a buffer
--- for any language server.
--- @param bufnr [number] buffer handle or 0 for current
--- @param client_id [number] the client id
+--- Implements the `textDocument/did…` notifications required to track a buffer
+--- for any language server.
+---
+--- Without calling this, the server won't be notified of changes to a buffer.
+---
+--- @param bufnr (number) Buffer handle, or 0 for current
+--- @param client_id (number) Client id
 function lsp.buf_attach_client(bufnr, client_id)
   validate {
     bufnr     = {bufnr, 'n', true};
@@ -683,28 +746,33 @@ function lsp.buf_attach_client(bufnr, client_id)
   return true
 end
 
--- Check if a buffer is attached for a particular client.
--- @param bufnr [number] buffer handle or 0 for current
--- @param client_id [number] the client id
+--- Checks if a buffer is attached for a particular client.
+---
+---@param bufnr (number) Buffer handle, or 0 for current
+---@param client_id (number) the client id
 function lsp.buf_is_attached(bufnr, client_id)
   return (all_buffer_active_clients[bufnr] or {})[client_id] == true
 end
 
--- Look up an active client by its id, returns nil if it is not yet initialized
--- or is not a valid id.
--- @param client_id number the client id.
+--- Gets an active client by id, or nil if the id is invalid or the
+--- client is not yet initialized.
+---
+--@param client_id client id number
+---
+--@return |vim.lsp.client| object, or nil
 function lsp.get_client_by_id(client_id)
   return active_clients[client_id]
 end
 
--- Stop a client by its id, optionally with force.
--- You can also use the `stop()` function on a client if you already have
--- access to it.
--- By default, it will just ask the server to shutdown without force.
--- If you request to stop a client which has previously been requested to shutdown,
--- it will automatically force shutdown.
--- @param client_id number the client id.
--- @param force boolean (optional) whether to use force or request shutdown
+--- Stops a client.
+---
+--- You can also use the `stop()` function on a |vim.lsp.client| object.
+---
+--- By default asks the server to shutdown, unless stop was requested
+--- already for this client, then force-shutdown is attempted.
+---
+--@param client_id client id number
+--@param force boolean (optional) shutdown forcefully
 function lsp.stop_client(client_id, force)
   local client
   client = active_clients[client_id]
@@ -718,18 +786,16 @@ function lsp.stop_client(client_id, force)
   end
 end
 
--- Returns a list of all the active clients.
+--- Gets all active clients.
+---
+--@return Table of |vim.lsp.client| objects
 function lsp.get_active_clients()
   return vim.tbl_values(active_clients)
 end
 
--- Stop all the clients, optionally with force.
--- You can also use the `stop()` function on a client if you already have
--- access to it.
--- By default, it will just ask the server to shutdown without force.
--- If you request to stop a client which has previously been requested to shutdown,
--- it will automatically force shutdown.
--- @param force boolean (optional) whether to use force or request shutdown
+--- Stops all clients.
+---
+--@param force boolean (optional) shutdown forcefully
 function lsp.stop_all_clients(force)
   for _, client in pairs(uninitialized_clients) do
     client.stop(true)
@@ -761,17 +827,21 @@ end
 
 nvim_command("autocmd VimLeavePre * lua vim.lsp._vim_exit_handler()")
 
----
---- Buffer level client functions.
----
 
---- Send a request to a server and return the response
--- @param bufnr [number] Buffer handle or 0 for current.
--- @param method [string] Request method name
--- @param params [table|nil] Parameters to send to the server
--- @param callback [function|nil] Request callback (or uses the client's callbacks)
+--- Sends an async request for all active clients attached to the
+--- buffer.
+---
+--@param bufnr (number) Buffer handle, or 0 for current.
+--@param method (string) LSP method name
+--@param params (optional, table) Parameters to send to the server
+--@param callback (optional, functionnil) Handler
+--  `function(err, method, params, client_id)` for this request. Defaults
+--  to the client callback in `client.callbacks`. See |lsp-callbacks|.
 --
--- @returns: client_request_ids, cancel_all_requests
+--@returns 2-tuple:
+---  - Map of client-id:request-id pairs for all successful requests.
+---  - Function which can be used to cancel all the requests. You could instead
+---    iterate all clients and call their `cancel_request()` methods.
 function lsp.buf_request(bufnr, method, params, callback)
   validate {
     bufnr    = { bufnr, 'n', true };
@@ -789,31 +859,39 @@ function lsp.buf_request(bufnr, method, params, callback)
     end
   end)
 
-  local function cancel_all_requests()
+  local function _cancel_all_requests()
     for client_id, request_id in pairs(client_request_ids) do
       local client = active_clients[client_id]
       client.cancel_request(request_id)
     end
   end
 
-  return client_request_ids, cancel_all_requests
+  return client_request_ids, _cancel_all_requests
 end
 
---- Send a request to a server and wait for the response.
--- @param bufnr [number] Buffer handle or 0 for current.
--- @param method [string] Request method name
--- @param params [string] Parameters to send to the server
--- @param timeout_ms [number|100] Maximum ms to wait for a result
---
--- @returns: The table of {[client_id] = request_result}
+--- Sends a request to a server and waits for the response.
+---
+--- Calls |vim.lsp.buf_request()| but blocks Nvim while awaiting the result.
+--- Parameters are the same as |vim.lsp.buf_request()| but the return result is
+--- different. Wait maximum of {timeout_ms} (default 100) ms.
+---
+--@param bufnr (number) Buffer handle, or 0 for current.
+--@param method (string) LSP method name
+--@param params (optional, table) Parameters to send to the server
+--@param timeout_ms (optional, number, default=100) Maximum time in
+---      milliseconds to wait for a result.
+---
+--@returns Map of client_id:request_result. On timeout, cancel or error,
+---        returns `(nil, err)` where `err` is a string describing the failure
+---        reason.
 function lsp.buf_request_sync(bufnr, method, params, timeout_ms)
   local request_results = {}
   local result_count = 0
-  local function callback(err, _method, result, client_id)
+  local function _callback(err, _method, result, client_id)
     request_results[client_id] = { error = err, result = result }
     result_count = result_count + 1
   end
-  local client_request_ids, cancel = lsp.buf_request(bufnr, method, params, callback)
+  local client_request_ids, cancel = lsp.buf_request(bufnr, method, params, _callback)
   local expected_result_count = 0
   for _ in pairs(client_request_ids) do
     expected_result_count = expected_result_count + 1
@@ -828,12 +906,13 @@ function lsp.buf_request_sync(bufnr, method, params, timeout_ms)
   return request_results
 end
 
---- Send a notification to a server
--- @param bufnr [number] (optional): The number of the buffer
--- @param method [string]: Name of the request method
--- @param params [string]: Arguments to send to the server
---
--- @returns nil
+--- Sends a notification to all servers attached to the buffer.
+---
+--@param bufnr (optional, number) Buffer handle, or 0 for current
+--@param method (string) LSP method name
+--@param params (string) Parameters to send to the server
+---
+--@returns nil
 function lsp.buf_notify(bufnr, method, params)
   validate {
     bufnr    = { bufnr, 'n', true };
@@ -888,12 +967,10 @@ function lsp.client_is_stopped(client_id)
   return active_clients[client_id] == nil
 end
 
+--- Gets a map of client_id:client pairs for the given buffer, where each value
+--- is a |vim.lsp.client| object.
 ---
---- Miscellaneous utilities.
----
-
--- Retrieve a map from client_id to client of all active buffer clients.
--- @param bufnr [number] (optional): buffer handle or 0 for current
+--@param bufnr (optional, number): Buffer handle, or 0 for current
 function lsp.buf_get_clients(bufnr)
   bufnr = resolve_bufnr(bufnr)
  local result = {}
@@ -903,8 +980,9 @@ function lsp.buf_get_clients(bufnr)
  return result
 end
 
--- Print some debug information about the current buffer clients.
--- The output of this function should not be relied upon and may change.
+--- Prints debug info about the current buffer clients.
+---
+--- Result of this function cannot be relied upon and may change.
 function lsp.buf_print_debug_info(bufnr)
   print(vim.inspect(lsp.buf_get_clients(bufnr)))
 end
@@ -919,14 +997,20 @@ end
 --
 -- Can be used to lookup the number from the name or the
 -- name from the number.
--- Levels by name: 'trace', 'debug', 'info', 'warn', 'error'
--- Level numbers begin with 'trace' at 0
+-- Levels by name: "trace", "debug", "info", "warn", "error"
+-- Level numbers begin with "trace" at 0
 lsp.log_levels = log.levels
 
--- Set the log level for lsp logging.
--- Levels by name: 'trace', 'debug', 'info', 'warn', 'error'
--- Level numbers begin with 'trace' at 0
--- @param level [number|string] the case insensitive level name or number @see |vim.lsp.log_levels|
+--- Sets the global log level for LSP logging.
+---
+--- Levels by name: "trace", "debug", "info", "warn", "error"
+--- Level numbers begin with "trace" at 0
+---
+--- Use `lsp.log_levels` for reverse lookup.
+---
+--@see |vim.lsp.log_levels|
+---
+--@param level [number|string] the case insensitive level name or number
 function lsp.set_log_level(level)
   if type(level) == 'string' or type(level) == 'number' then
     log.set_level(level)
@@ -935,7 +1019,7 @@ function lsp.set_log_level(level)
   end
 end
 
--- Return the path of the logfile used by the LSP client.
+--- Gets the path of the logfile used by the LSP client.
 function lsp.get_log_path()
   return log.get_filename()
 end
diff --git a/runtime/lua/vim/lsp/protocol.lua b/runtime/lua/vim/lsp/protocol.lua
index ead90cc75a..f64b0b50e7 100644
--- a/runtime/lua/vim/lsp/protocol.lua
+++ b/runtime/lua/vim/lsp/protocol.lua
@@ -603,6 +603,8 @@ export interface WorkspaceClientCapabilities {
 }
 --]=]
 
+--- Gets a new ClientCapabilities object describing the LSP client
+--- capabilities.
 function protocol.make_client_capabilities()
   return {
     textDocument = {
@@ -821,6 +823,8 @@ interface ServerCapabilities {
   experimental?: any;
 }
 --]]
+
+--- Creates a normalized object describing LSP server capabilities.
 function protocol.resolve_capabilities(server_capabilities)
   local general_properties = {}
   local text_document_sync_properties
diff --git a/runtime/lua/vim/lsp/rpc.lua b/runtime/lua/vim/lsp/rpc.lua
index 72a0bf8d6f..e13b05610b 100644
--- a/runtime/lua/vim/lsp/rpc.lua
+++ b/runtime/lua/vim/lsp/rpc.lua
@@ -166,9 +166,14 @@ local function format_rpc_error(err)
   return table.concat(message_parts, ' ')
 end
 
+--- Creates an RPC response object/table.
+---
+--@param code RPC error code defined in `vim.lsp.protocol.ErrorCodes`
+--@param message (optional) arbitrary message to send to server
+--@param data (optional) arbitrary data to send to server
 local function rpc_response_error(code, message, data)
   -- TODO should this error or just pick a sane error (like InternalError)?
-  local code_name = assert(protocol.ErrorCodes[code], 'Invalid rpc error code')
+  local code_name = assert(protocol.ErrorCodes[code], 'Invalid RPC error code')
   return setmetatable({
     code = code;
     message = message or code_name;