Merge pull request #12708 from runiq/lsp-doc

Add docs for some methods in vim.lsp

9 files changed, 1242 insertions, 459 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index ea3a8242ae..7ac7f7d7ea 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -734,13 +734,14 @@ nvim_feedkeys({keys}, {mode}, {escape_csi})                  *nvim_feedkeys()*
 
                 On execution error: does not fail, but updates v:errmsg.
 
-                If you need to input sequences like <C-o> use nvim_replace_termcodes
-                to replace the termcodes and then pass the resulting string to
-                nvim_feedkeys. You'll also want to enable escape_csi.
+                If you need to input sequences like <C-o> use
+                |nvim_replace_termcodes| to replace the termcodes and then
+                pass the resulting string to nvim_feedkeys. You'll also want
+                to enable escape_csi.
 
                 Example: >
-		    :let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true)
-		    :call nvim_feedkeys(key, 'n', v:true)
+                    :let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true)
+                    :call nvim_feedkeys(key, 'n', v:true)
 <
 
                 Parameters: ~
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index b934d2dfa0..9db478ac41 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -353,9 +353,6 @@ buf_get_clients({bufnr})                           *vim.lsp.buf_get_clients()*
                     {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.
 
@@ -416,71 +413,69 @@ buf_request_sync({bufnr}, {method}, {params}, {timeout_ms})
                     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.
+                LSP client object. You can get an active client object via
+                |vim.lsp.get_client_by_id()| or
+                |vim.lsp.get_active_clients()|.
 
                 • Methods:
-                  • request(method, params, [callback]) Send a request to the
-                    server. If callback is not specified, it will use
+                  • request(method, params, [callback], bufnr) Send a request
+                    to the server. This is a thin wrapper around
+                    {client.rpc.request} with some additional checking. 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()` .
+                    not found there, then an error will occur. Returns:
+                    {status}, {[client_id]}. {status} is a boolean indicating
+                    if the notification was successful. If it is `false` ,
+                    then it will always be `false` (the client has shutdown).
+                    If {status} is `true` , the function returns {request_id}
+                    as the second result. You can use this with
+                    `client.cancel_request(request_id)` to cancel the request.
+                  • notify(method, params) Send a notification to an LSP
+                    server. Returns: a boolean to indicate if the notification
+                    was successful. If it is false, then it will always be
+                    false (the client has shutdown).
+                  • cancel_request(id) Cancels a request with a given request
+                    id. Returns: 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.
+                  • is_stopped() Checks whether a client is stopped. Returns:
+                    true if the client is fully stopped.
+                  • on_attach(bufnr) Runs the on_attach function from the
+                    client's config if it was defined.
 
                 • Members
-                  • id (number): The id allocated to the client.
-                  • name (string): If a name is specified on creation, that
+                  • {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
+                  • {rpc} (table): RPC client object, for low level
+                    interaction with the client. See |vim.lsp.rpc.start()|.
+                  • {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
+                    `config` 's `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
+                  • {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
+                  • {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
+                Checks whether a client is stopped.
 
-                                               *vim.lsp.define_default_sign()*
-define_default_sign({name}, {properties})
-                TODO: Documentation
-
-err_message({...})                                     *vim.lsp.err_message()*
-                TODO: Documentation
+                Parameters: ~
+                    {client_id}  (Number)
 
-                                            *vim.lsp.for_each_buffer_client()*
-for_each_buffer_client({bufnr}, {callback})
-                TODO: Documentation
+                Return: ~
+                    true if client is stopped, false otherwise.
 
 get_active_clients()                            *vim.lsp.get_active_clients()*
                 Gets all active clients.
@@ -499,25 +494,10 @@ get_client_by_id({client_id})                     *vim.lsp.get_client_by_id()*
                     |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
+                Gets the path of the logfile used by the LSP client.
 
-next_client_id()                                    *vim.lsp.next_client_id()*
-                TODO: Documentation
-
-notification({method}, {params})                      *vim.lsp.notification()*
-                TODO: Documentation
-
-notify({...})                                               *vim.lsp.notify()*
-                TODO: Documentation
+                Return: ~
+                    (String) Path to logfile.
 
 omnifunc({findstart}, {base})                             *vim.lsp.omnifunc()*
                 Implements 'omnifunc' compatible LSP completion.
@@ -538,30 +518,6 @@ omnifunc({findstart}, {base})                             *vim.lsp.omnifunc()*
                     |complete-items|
                     |CompleteDone|
 
-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
-
-request({method}, {params}, {callback}, {bufnr})           *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.
 
@@ -582,6 +538,9 @@ start_client({config})                                *vim.lsp.start_client()*
 
                 Parameters `cmd` and `root_dir` are required.
 
+                The following parameters describe fields in the {config}
+                table.
+
                 Parameters: ~
                     {root_dir}         (required, string) Directory where the
                                        LSP server will base its rootUri on
@@ -612,13 +571,13 @@ start_client({config})                                *vim.lsp.start_client()*
                                          array.
                     {callbacks}        Map of language server method names to `function(err, method, params,
                                        client_id)` handler. Invoked for:
-                                       • Notifications from the server, where
+                                       • Notifications to 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
+                                       • Requests 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
@@ -647,8 +606,9 @@ start_client({config})                                *vim.lsp.start_client()*
                                        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.
+                                       |vim.lsp.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`
@@ -680,9 +640,6 @@ start_client({config})                                *vim.lsp.start_client()*
                     error). Use `on_init` to do any actions once the client
                     has been initialized.
 
-stop({force})                                                 *vim.lsp.stop()*
-                TODO: Documentation
-
 stop_client({client_id}, {force})                      *vim.lsp.stop_client()*
                 Stops a client(s).
 
@@ -702,26 +659,10 @@ stop_client({client_id}, {force})                      *vim.lsp.stop_client()*
                                  thereof
                     {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_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
@@ -739,28 +680,38 @@ resolve_capabilities({server_capabilities})
                 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*
 
 clear_references()                            *vim.lsp.buf.clear_references()*
-                TODO: Documentation
+                Removes document highlights from current buffer.
 
 code_action({context})                             *vim.lsp.buf.code_action()*
-                TODO: Documentation
+                Select a code action from the input list that is available at
+                the current cursor position.
+
+                Parameters: ~
+                    {context}  (table, optional) Valid `CodeActionContext`
+                               object
+
+                See also: ~
+                    https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeAction
 
 completion({context})                               *vim.lsp.buf.completion()*
                 Retrieves the completion items at the current cursor position.
                 Can only be called in Insert mode.
 
+                Parameters: ~
+                    {context}  (context support not yet implemented)
+                               Additional information about the context in
+                               which a completion was triggered (how it was
+                               triggered, and by which trigger character, if
+                               applicable)
+
+                See also: ~
+                    |vim.lsp.protocol.constants.CompletionTriggerKind|
+
 declaration()                                      *vim.lsp.buf.declaration()*
                 Jumps to the declaration of the symbol under the cursor.
 
@@ -782,14 +733,25 @@ document_symbol()                              *vim.lsp.buf.document_symbol()*
                 window.
 
 execute_command({command})                     *vim.lsp.buf.execute_command()*
-                TODO: Documentation
+                Execute an LSP server command.
+
+                Parameters: ~
+                    {command}  A valid `ExecuteCommandParams` object
+
+                See also: ~
+                    https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_executeCommand
 
 formatting({options})                               *vim.lsp.buf.formatting()*
                 Formats the current buffer.
 
-                The optional {options} table can be used to specify
-                FormattingOptions, a list of which is available at https://microsoft.github.io/language-server-protocol/specification#textDocument_formatting . Some unspecified options will be automatically derived from
-                the current Neovim options.
+                Parameters: ~
+                    {options}  (optional, table) Can be used to specify
+                               FormattingOptions. Some unspecified options
+                               will be automatically derived from the current
+                               Neovim options.
+
+                See also: ~
+                    https://microsoft.github.io/language-server-protocol/specification#textDocument_formatting
 
                                                *vim.lsp.buf.formatting_sync()*
 formatting_sync({options}, {timeout_ms})
@@ -797,7 +759,15 @@ formatting_sync({options}, {timeout_ms})
 
                 Useful for running on save, to make sure buffer is formatted
                 prior to being saved. {timeout_ms} is passed on to
-                |vim.lsp.buf_request_sync()|.
+                |vim.lsp.buf_request_sync()|. Example:
+>
+
+    vim.api.nvim_command[[autocmd BufWritePre <buffer> lua vim.lsp.buf.formatting_sync()]]
+<
+
+                Parameters: ~
+                    {options}     Table with valid `FormattingOptions` entries
+                    {timeout_ms}  (number) Request timeout
 
 hover()                                                  *vim.lsp.buf.hover()*
                 Displays hover information about the symbol under the cursor
@@ -808,29 +778,49 @@ implementation()                                *vim.lsp.buf.implementation()*
                 Lists all the implementations for the symbol under the cursor
                 in the quickfix window.
 
-npcall({fn}, {...})                                     *vim.lsp.buf.npcall()*
-                TODO: Documentation
+incoming_calls()                                *vim.lsp.buf.incoming_calls()*
+                Lists all the call sites of the symbol under the cursor in the
+                |quickfix| window. If the symbol can resolve to multiple
+                items, the user can pick one in the |inputlist|.
 
-ok_or_nil({status}, {...})                           *vim.lsp.buf.ok_or_nil()*
-                TODO: Documentation
+outgoing_calls()                                *vim.lsp.buf.outgoing_calls()*
+                Lists all the items that are called by the symbol under the
+                cursor in the |quickfix| window. If the symbol can resolve to
+                multiple items, the user can pick one in the |inputlist|.
 
                                               *vim.lsp.buf.range_formatting()*
 range_formatting({options}, {start_pos}, {end_pos})
-                TODO: Documentation
+                Perform |vim.lsp.buf.formatting()| synchronously.
+
+                Useful for running on save, to make sure buffer is formatted
+                prior to being saved. {timeout_ms} is passed on to
+                |vim.lsp.buf_request_sync()|.
+
+                Parameters: ~
+                    {options}     Table with valid `FormattingOptions` entries
+                    {timeout_ms}  (number) Request timeout
 
 references({context})                               *vim.lsp.buf.references()*
                 Lists all the references to the symbol under the cursor in the
                 quickfix window.
 
+                Parameters: ~
+                    {context}  (table) Context for the request
+
+                See also: ~
+                    https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_references
+
 rename({new_name})                                      *vim.lsp.buf.rename()*
-                Renames all references to the symbol under the cursor. If
-                {new_name} is not provided, the user will be prompted for a
-                new name using |input()|.
+                Renames all references to the symbol under the cursor.
 
-request({method}, {params}, {callback})                *vim.lsp.buf.request()*
-                TODO: Documentation
+                Parameters: ~
+                    {new_name}  (string) If not provided, the user will be
+                                prompted for a new name using |input()|.
 
 server_ready()                                    *vim.lsp.buf.server_ready()*
+                Checks whether the language servers attached to the current
+                buffer are ready.
+
                 Return: ~
                     `true` if server responds.
 
@@ -846,115 +836,75 @@ workspace_symbol({query})                     *vim.lsp.buf.workspace_symbol()*
                 Lists all symbols in the current workspace in the quickfix
                 window.
 
-                The list is filtered against the optional argument {query}; if
-                the argument is omitted from the call, the user is prompted to
-                enter a string on the command line. An empty string means no
-                filtering is done.
+                The list is filtered against {query}; if the argument is
+                omitted from the call, the user is prompted to enter a string
+                on the command line. An empty string means no filtering is
+                done.
 
-incoming_calls()                               *vim.lsp.buf.incoming_calls()*
-                Lists all the call sites of the symbol under the cursor in the
-                |quickfix| window. If the symbol can resolve to multiple
-                items, the user can pick one in the |inputlist|.
-
-outgoing_calls()                               *vim.lsp.buf.outgoing_calls()*
-                Lists all the items that are called by the symbol under the
-                cursor in the |quickfix| window. If the symbol can resolve to
-                multiple items, the user can pick one in the |inputlist|.
-
-
-==============================================================================
-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
+                Parameters: ~
+                    {query}  (string, optional)
 
 
 ==============================================================================
 Lua module: vim.lsp.log                                              *lsp-log*
 
 get_filename()                                    *vim.lsp.log.get_filename()*
-                TODO: Documentation
+                Returns the log filename.
 
-path_join({...})                                     *vim.lsp.log.path_join()*
-                TODO: Documentation
+                Return: ~
+                    (string) log filename
 
 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*
+                Sets the current log level.
 
-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
+                Parameters: ~
+                    {level}  (string or number) One of `vim.lsp.log.levels`
 
-encode_and_send({payload})                     *vim.lsp.rpc.encode_and_send()*
-                TODO: Documentation
+should_log({level})                                 *vim.lsp.log.should_log()*
+                Checks whether the level is sufficient for logging.
 
-env_merge({env})                                     *vim.lsp.rpc.env_merge()*
-                Merges current process env with the given env and returns the
-                result as a list of "k=v" strings.
->
+                Parameters: ~
+                    {level}  number log level
 
-    Example:
-<
+                Return: ~
+                    (bool) true if would log, false if not
 
-                > in:    { PRODUCTION="false", PATH="/usr/bin/", PORT=123, HOST="0.0.0.0", }
-                 out:   { "PRODUCTION=false", "PATH=/usr/bin/", "PORT=123", "HOST=0.0.0.0", }
-<
 
-                            *vim.lsp.rpc.format_message_with_content_length()*
-format_message_with_content_length({encoded_message})
-                TODO: Documentation
+==============================================================================
+Lua module: vim.lsp.rpc                                              *lsp-rpc*
 
 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
+                Constructs an error message from an LSP error object.
 
-json_decode({data})                                *vim.lsp.rpc.json_decode()*
-                TODO: Documentation
-
-json_encode({data})                                *vim.lsp.rpc.json_encode()*
-                TODO: Documentation
+                Parameters: ~
+                    {err}  (table) The error object
 
-notification({method}, {params})                  *vim.lsp.rpc.notification()*
-                TODO: Documentation
+                Return: ~
+                    (string) The formatted error message
 
-on_error({errkind}, {...})                            *vim.lsp.rpc.on_error()*
-                TODO: Documentation
+notify({method}, {params})                              *vim.lsp.rpc.notify()*
+                Sends a notification to the LSP server.
 
-on_exit({code}, {signal})                              *vim.lsp.rpc.on_exit()*
-                TODO: Documentation
+                Parameters: ~
+                    {method}  (string) The invoked LSP method
+                    {params}  (table): Parameters for the invoked LSP method
 
-onexit({code}, {signal})                                *vim.lsp.rpc.onexit()*
-                TODO: Documentation
+                Return: ~
+                    (bool) `true` if notification could be sent, `false` if
+                    not
 
-parse_headers({header})                          *vim.lsp.rpc.parse_headers()*
-                TODO: Documentation
+request({method}, {params}, {callback})                *vim.lsp.rpc.request()*
+                Sends a request to the LSP server and runs {callback} upon
+                response.
 
-                                                 *vim.lsp.rpc.pcall_handler()*
-pcall_handler({errkind}, {status}, {head}, {...})
-                TODO: Documentation
+                Parameters: ~
+                    {method}    (string) The invoked LSP method
+                    {params}    (table) Parameters for the invoked LSP method
+                    {callback}  (function) Callback to invoke
 
-request_parser_loop()                      *vim.lsp.rpc.request_parser_loop()*
-                TODO: Documentation
+                Return: ~
+                    (bool, number) `(true, message_id)` if request could be
+                    sent, `false` if not
 
                                             *vim.lsp.rpc.rpc_response_error()*
 rpc_response_error({code}, {message}, {data})
@@ -966,48 +916,84 @@ rpc_response_error({code}, {message}, {data})
                     {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.start()*
+start({cmd}, {cmd_args}, {handlers}, {extra_spawn_params})
+                Start an LSP server process and create an LSP RPC client
+                object to interact with it.
 
-                                                  *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
+                Parameters: ~
+                    {cmd}                 (string) Command to start the LSP
+                                          server.
+                    {cmd_args}            (table) List of additional string
+                                          arguments to pass to {cmd}.
+                    {handlers}            (table, optional) Handlers for LSP
+                                          message types. Valid handler names
+                                          are:
+                                          • `"notification"`
+                                          • `"server_request"`
+                                          • `"on_error"`
+                                          • `"on_exit"`
+                    {extra_spawn_params}  (table, optional) Additional context
+                                          for the LSP server process. May
+                                          contain:
+                                          • {cwd} (string) Working directory
+                                            for the LSP server process
+                                          • {env} (table) Additional
+                                            environment variables for LSP
+                                            server process
 
-server_request({method}, {params})              *vim.lsp.rpc.server_request()*
-                TODO: Documentation
+                Return: ~
+                    Client RPC object.
+                    Methods:
+                    • `notify()` |vim.lsp.rpc.notify()|
+                    • `request()` |vim.lsp.rpc.request()|
 
-try_call({errkind}, {fn}, {...})                      *vim.lsp.rpc.try_call()*
-                TODO: Documentation
+                    Members:
+                    • {pid} (number) The LSP server's PID.
+                    • {handle} A handle for low-level interaction with the LSP
+                      server process |vim.loop|.
 
 
 ==============================================================================
 Lua module: vim.lsp.util                                            *lsp-util*
 
-                                       *vim.lsp.util.apply_syntax_to_region()*
-apply_syntax_to_region({ft}, {start}, {finish})
-                TODO: Documentation
-
                                      *vim.lsp.util.apply_text_document_edit()*
 apply_text_document_edit({text_document_edit})
-                TODO: Documentation
+                Apply a `TextDocumentEdit` , which is a list of changes to a
+                single document.
+
+                Parameters: ~
+                    {text_document_edit}  (table) a `TextDocumentEdit` object
+
+                See also: ~
+                    https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentEdit
 
                                              *vim.lsp.util.apply_text_edits()*
 apply_text_edits({text_edits}, {bufnr})
-                TODO: Documentation
+                Applies a list of text edits to a buffer.
+
+                Parameters: ~
+                    {text_edits}  (table) list of `TextEdit` objects
+                    {buf_nr}      (number) Buffer id
 
                                          *vim.lsp.util.apply_workspace_edit()*
 apply_workspace_edit({workspace_edit})
-                TODO: Documentation
+                Applies a `WorkspaceEdit` .
+
+                Parameters: ~
+                    {workspace_edit}  (table) `WorkspaceEdit`
 
 buf_clear_diagnostics({bufnr})          *vim.lsp.util.buf_clear_diagnostics()*
-                TODO: Documentation
+                Clear diagnostics for a buffer.
+
+                Parameters: ~
+                    {bufnr}  (number) buffer id
 
 buf_clear_references({bufnr})            *vim.lsp.util.buf_clear_references()*
-                TODO: Documentation
+                Removes document highlights from a buffer.
+
+                Parameters: ~
+                    {bufnr}  buffer id
 
 buf_diagnostics_count({kind})           *vim.lsp.util.buf_diagnostics_count()*
                 Returns the number of diagnostics of given kind for current
@@ -1040,12 +1026,14 @@ buf_diagnostics_count({kind})           *vim.lsp.util.buf_diagnostics_count()*
 
                                *vim.lsp.util.buf_diagnostics_save_positions()*
 buf_diagnostics_save_positions({bufnr}, {diagnostics})
-                Saves the diagnostics (Diagnostic[]) into diagnostics_by_buf
+                Saves diagnostics into
+                vim.lsp.util.diagnostics_by_buf[{bufnr}].
 
                 Parameters: ~
-                    {bufnr}        bufnr for which the diagnostics are for.
-                    {diagnostics}  Diagnostics[] received from the language
-                                   server.
+                    {bufnr}        (number) buffer id for which the
+                                   diagnostics are for
+                    {diagnostics}  list of `Diagnostic` s received from the
+                                   LSP server
 
                                         *vim.lsp.util.buf_diagnostics_signs()*
 buf_diagnostics_signs({bufnr}, {diagnostics})
@@ -1061,38 +1049,117 @@ buf_diagnostics_signs({bufnr}, {diagnostics})
 
                                     *vim.lsp.util.buf_diagnostics_underline()*
 buf_diagnostics_underline({bufnr}, {diagnostics})
-                TODO: Documentation
+                Highlights a list of diagnostics in a buffer by underlining
+                them.
+
+                Parameters: ~
+                    {bufnr}        (number) buffer id
+                    {diagnostics}  (list of `Diagnostic` s)