Merge pull request #12708 from runiq/lsp-doc

Add docs for some methods in vim.lsp

2 files changed, 501 insertions, 324 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)
 
                                  *vim.lsp.util.buf_diagnostics_virtual_text()*
 buf_diagnostics_virtual_text({bufnr}, {diagnostics})
-                TODO: Documentation
+                Given a list of diagnostics, set the corresponding virtual
+                text for a buffer.
+
+                Parameters: ~
+                    {bufnr}        buffer id
+                    {diagnostics}  (table) list of `Diagnostic` s
 
                                      *vim.lsp.util.buf_highlight_references()*
 buf_highlight_references({bufnr}, {references})
-                TODO: Documentation
+                Show a list of document highlights for a certain buffer.
+
+                Parameters: ~
+                    {bufnr}       buffer id
+                    {references}  List of `DocumentHighlight` objects to
+                                  highlight
 
 character_offset({buf}, {row}, {col})        *vim.lsp.util.character_offset()*
-                TODO: Documentation
+                Returns the UTF-32 and UTF-16 offsets for a position in a
+                certain buffer.
+
+                Parameters: ~
+                    {buf}  buffer id (0 for current)
+                    {row}  0-indexed line
+                    {col}  0-indexed byte offset in line
+
+                Return: ~
+                    (number, number) UTF-32 and UTF-16 index of the character
+                    in line {row} column {col} in buffer {buf}
 
                                         *vim.lsp.util.close_preview_autocmd()*
 close_preview_autocmd({events}, {winnr})
-                TODO: Documentation
+                Create autocommands to close a preview window when events
+                happen.
+
+                Parameters: ~
+                    {events}  (table) list of events
+                    {winnr}   (number) window id of preview window
+
+                See also: ~
+                    |autocmd-events|
 
                               *vim.lsp.util.convert_input_to_markdown_lines()*
 convert_input_to_markdown_lines({input}, {contents})
-                TODO: Documentation
+                Convert any of `MarkedString` | `MarkedString[]` |
+                `MarkupContent` into a list of lines containing valid
+                markdown. Useful to populate the hover window for
+                `textDocument/hover` , for parsing the result of
+                `textDocument/signatureHelp` , and potentially others.
+
+                Parameters: ~
+                    {input}     ( `MarkedString` | `MarkedString[]` |
+                                `MarkupContent` )
+                    {contents}  (table, optional, default `{}` ) List of
+                                strings to extend with converted lines
+
+                Return: ~
+                    {contents}, extended with lines of converted markdown.
+
+                See also: ~
+                    https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover
 
                      *vim.lsp.util.convert_signature_help_to_markdown_lines()*
 convert_signature_help_to_markdown_lines({signature_help})
-                TODO: Documentation
+                Convert `textDocument/SignatureHelp` response to markdown
+                lines.
+
+                Parameters: ~
+                    {signature_help}  Response of `textDocument/SignatureHelp`
+
+                Return: ~
+                    list of lines of converted markdown.
+
+                See also: ~
+                    https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_signatureHelp
 
                                     *vim.lsp.util.diagnostics_group_by_line()*
 diagnostics_group_by_line({diagnostics})
-                TODO: Documentation
+                Groups a list of diagnostics by line.
+
+                Parameters: ~
+                    {diagnostics}  (table) list of `Diagnostic` s
+
+                Return: ~
+                    (table) dictionary mapping lines to lists of diagnostics
+                    valid on those lines
+
+                See also: ~
+                    https://microsoft.github.io/language-server-protocol/specifications/specification-current/#diagnostic
 
                                      *vim.lsp.util.extract_completion_items()*
 extract_completion_items({result})
-                TODO: Documentation
+                Can be used to extract the completion items from a `textDocument/completion` request, which may return one of `CompletionItem[]` , `CompletionList` or null.
+
+                Parameters: ~
+                    {result}  (table) The result of a
+                              `textDocument/completion` request
+
+                Return: ~
+                    (table) List of completion items
+
+                See also: ~
+                    https://microsoft.github.io/language-server-protocol/specification#textDocument_completion
 
                                       *vim.lsp.util.fancy_floating_markdown()*
 fancy_floating_markdown({contents}, {opts})
@@ -1100,8 +1167,7 @@ fancy_floating_markdown({contents}, {opts})
                 the code blocks and converting them into highlighted code.
                 This will by default insert a blank line separator after those
                 code block regions to improve readability. The result is shown
-                in a floating preview TODO: refactor to separate
-                stripping/converting and make use of open_floating_preview
+                in a floating preview
 
                 Parameters: ~
                     {contents}  table of lines to show in window
@@ -1110,22 +1176,34 @@ fancy_floating_markdown({contents}, {opts})
                 Return: ~
                     width,height size of float
 
-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
+                Parameters: ~
+                    {unique_name}  (string) Window variable
+                    {fn}           (function) should return create a new
+                                   window and return a tuple of
+                                   ({focusable_buffer_id}, {window_id}). if
+                                   {focusable_buffer_id} is a valid buffer id,
+                                   the newly created window will be the new
+                                   focus associated with the current buffer
+                                   via the tag `unique_name` .
+
+                Return: ~
+                    (pbufnr, pwinnr) if `fn()` has created a new window; nil
+                    otherwise
 
                                             *vim.lsp.util.focusable_preview()*
 focusable_preview({unique_name}, {fn})
-                TODO: Documentation
-
-get_completion_word({item})               *vim.lsp.util.get_completion_word()*
-                TODO: Documentation
+                Focus/unfocus the floating preview window associated with the
+                current buffer via the window variable `unique_name` . If no
+                such preview window exists, make a new one.
 
-                                   *vim.lsp.util.get_current_line_to_cursor()*
-get_current_line_to_cursor()
-                TODO: Documentation
+                Parameters: ~
+                    {unique_name}  (string) Window variable
+                    {fn}           (function) The return values of this
+                                   function will be passed directly to
+                                   |vim.lsp.util.open_floating_preview()|, in
+                                   the case that a new floating window should
+                                   be created
 
 get_effective_tabstop({bufnr})          *vim.lsp.util.get_effective_tabstop()*
                 Get visual width of tabstop.
@@ -1140,48 +1218,104 @@ get_effective_tabstop({bufnr})          *vim.lsp.util.get_effective_tabstop()*
                 See also: ~
                     |softtabstop|
 
-                                  *vim.lsp.util.get_line_byte_from_position()*
-get_line_byte_from_position({bufnr}, {position})
-                TODO: Documentation
-
 get_line_diagnostics()                   *vim.lsp.util.get_line_diagnostics()*
-                TODO: Documentation
+                Get list of diagnostics for the current line.
+
+                Return: ~
+                    (table) list of `Diagnostic` tables
+
+                See also: ~
+                    https://microsoft.github.io/language-server-protocol/specifications/specification-current/#diagnostic
 
                                   *vim.lsp.util.get_severity_highlight_name()*
 get_severity_highlight_name({severity})
-                TODO: Documentation
+                Get the name of a severity's highlight group.
+
+                Parameters: ~
+                    {severity}  A member of
+                                `vim.lsp.protocol.DiagnosticSeverity`
+
+                Return: ~
+                    (string) Highlight group name
 
 jump_to_location({location})                 *vim.lsp.util.jump_to_location()*
-                TODO: Documentation
+                Jumps to a location.
+
+                Parameters: ~
+                    {location}  ( `Location` | `LocationLink` )
+
+                Return: ~
+                    `true` if the jump succeeded
 
 locations_to_items({locations})            *vim.lsp.util.locations_to_items()*
-                TODO: Documentation
+                Returns the items with the byte position calculated correctly
+                and in sorted order, for display in quickfix and location
+                lists.
+
+                Parameters: ~
+                    {locations}  (table) list of `Location` s or
+                                 `LocationLink` s
+
+                Return: ~
+                    (table) list of items
 
                                   *vim.lsp.util.make_floating_popup_options()*
 make_floating_popup_options({width}, {height}, {opts})
-                TODO: Documentation
+                Creates a table with sensible default options for a floating
+                window. The table can be passed to |nvim_open_win()|.
+
+                Parameters: ~
+                    {width}   (number) window width (in character cells)
+                    {height}  (number) window height (in character cells)
+                    {opts}    (table, optional)
+
+                Return: ~
+                    (table) Options
 
                                        *vim.lsp.util.make_formatting_params()*
 make_formatting_params({options})
-                TODO: Documentation
+                Creates a `FormattingOptions` object for the current buffer
+                and cursor position.
 
-make_position_param()                     *vim.lsp.util.make_position_param()*
-                TODO: Documentation
+                Parameters: ~
+                    {options}  Table with valid `FormattingOptions` entries
+
+                Return: ~
+                    `FormattingOptions object
+
+                See also: ~
+                    https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_formatting
 
 make_position_params()                   *vim.lsp.util.make_position_params()*
-                TODO: Documentation
+                Creates a `TextDocumentPositionParams` object for the current
+                buffer and cursor position.
+
+                Return: ~
+                    `TextDocumentPositionParams` object
+
+                See also: ~
+                    https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentPositionParams
 
 make_range_params()                         *vim.lsp.util.make_range_params()*
-                TODO: Documentation
+                Using the current position in the current buffer, creates an
+                object that can be used as a building block for several LSP
+                requests, such as `textDocument/codeAction` ,
+                `textDocument/colorPresentation` ,
+                `textDocument/rangeFormatting` .
+
+                Return: ~
+                    { textDocument = { uri = `current_file_uri` }, range = {
+                    start = `current_position` , end = `current_position` } }
 
 make_text_document_params()         *vim.lsp.util.make_text_document_params()*
-                TODO: Documentation
+                Creates a `TextDocumentIdentifier` object for the current
+                buffer.
 
-npcall({fn}, {...})                                    *vim.lsp.util.npcall()*
-                TODO: Documentation
+                Return: ~
+                    `TextDocumentIdentifier`
 
-ok_or_nil({status}, {...})                          *vim.lsp.util.ok_or_nil()*
-                TODO: Documentation
+                See also: ~
+                    https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentIdentifier
 
                                         *vim.lsp.util.open_floating_preview()*
 open_floating_preview({contents}, {filetype}, {opts})
@@ -1193,17 +1327,20 @@ open_floating_preview({contents}, {filetype}, {opts})
                     {opts}      dictionary with optional fields
 
                 Return: ~
-                    bufnr,winnr buffer and window number of floating window or
-                    nil
+                    bufnr,winnr buffer and window number of the newly created
+                    floating preview window
 
 parse_snippet({input})                          *vim.lsp.util.parse_snippet()*
-                TODO: Documentation
+                Parses snippets in a completion entry.
 
-parse_snippet_rec({input}, {inner})         *vim.lsp.util.parse_snippet_rec()*
-                TODO: Documentation
+                Parameters: ~
+                    {input}  (string) unparsed snippet
+
+                Return: ~
+                    (string) parsed snippet
 
 preview_location({location})                 *vim.lsp.util.preview_location()*
-                Preview a location in a floating windows
+                Preview a location in a floating window
 
                 behavior depends on type of location:
                 • for Location, range is shown (e.g., function definition)
@@ -1211,36 +1348,45 @@ preview_location({location})                 *vim.lsp.util.preview_location()*
                   function definition)
 
                 Parameters: ~
-                    {location}  a single Location or LocationLink
+                    {location}  a single `Location` or `LocationLink`
 
                 Return: ~
-                    bufnr,winnr buffer and window number of floating window or
-                    nil
-
-                              *vim.lsp.util.remove_unmatch_completion_items()*
-remove_unmatch_completion_items({items}, {prefix})
-                TODO: Documentation
+                    (bufnr,winnr) buffer and window number of floating window
+                    or nil
 
 set_lines({lines}, {A}, {B}, {new_lines})           *vim.lsp.util.set_lines()*
-                TODO: Documentation
+                Replace text in a range with new text.
 
-set_loclist({items})                              *vim.lsp.util.set_loclist()*
-                TODO: Documentation
+                CAUTION: Changes in-place!
 
-set_qflist({items})                                *vim.lsp.util.set_qflist()*
-                TODO: Documentation
+                Parameters: ~
+                    {lines}      (table) Original list of strings
+                    {A}          (table) Start position; a 2-tuple of {line,
+                                 col} numbers
+                    {B}          (table) End position; a 2-tuple of {line,
+                                 col} numbers
+                    {new_lines}  A list of strings to replace the original
 
-show_line_diagnostics()                 *vim.lsp.util.show_line_diagnostics()*
-                TODO: Documentation
+                Return: ~
+                    (table) The modified {lines} object
 
-sort_by_key({fn})                                 *vim.lsp.util.sort_by_key()*
-                TODO: Documentation
+set_loclist({items})                              *vim.lsp.util.set_loclist()*
+                Fills current window's location list with given list of items.
+                Can be obtained with e.g. |vim.lsp.util.locations_to_items()|.
 
-sort_completion_items({items})          *vim.lsp.util.sort_completion_items()*
-                TODO: Documentation
+                Parameters: ~
+                    {items}  (table) list of items
 
-split_lines({value})                              *vim.lsp.util.split_lines()*
-                TODO: Documentation
+set_qflist({items})                                *vim.lsp.util.set_qflist()*
+                Fills quickfix list with given list of items. Can be obtained
+                with e.g. |vim.lsp.util.locations_to_items()|.
+
+                Parameters: ~
+                    {items}  (table) list of items
+
+show_line_diagnostics()                 *vim.lsp.util.show_line_diagnostics()*
+                Displays the diagnostics for the current line in a floating
+                hover window.
 
 symbols_to_items({symbols}, {bufnr})         *vim.lsp.util.symbols_to_items()*
                 Convert symbols to quickfix list items
@@ -1250,13 +1396,43 @@ symbols_to_items({symbols}, {bufnr})         *vim.lsp.util.symbols_to_items()*
 
               *vim.lsp.util.text_document_completion_list_to_complete_items()*
 text_document_completion_list_to_complete_items({result}, {prefix})
-                TODO: Documentation
+                Turns the result of a `textDocument/completion` request into
+                vim-compatible |complete-items|.
+
+                Parameters: ~
+                    {result}  The result of a `textDocument/completion` call,
+                              e.g. from |vim.lsp.buf.completion()|, which may
+                              be one of `CompletionItem[]` , `CompletionList`
+                              or `null`
+                    {prefix}  (string) the prefix to filter the completion
+                              items
+
+                Return: ~
+                    { matches = complete-items table, incomplete = bool }
+
+                See also: ~
+                    |complete-items|
 
 trim_empty_lines({lines})                    *vim.lsp.util.trim_empty_lines()*
-                TODO: Documentation
+                Remove empty lines from the beginning and end.
+
+                Parameters: ~
+                    {lines}  (table) list of lines to trim
+
+                Return: ~
+                    (table) trimmed list of lines
 
                                 *vim.lsp.util.try_trim_markdown_code_blocks()*
 try_trim_markdown_code_blocks({lines})
-                TODO: Documentation
+                Accepts markdown lines and tries to reduce them to a filetype
+                if they comprise just a single code block.
+
+                CAUTION: Modifies the input in-place!
+
+                Parameters: ~
+                    {lines}  (table) list of lines
+
+                Return: ~
+                    (string) filetype or 'markdown' if it was unchanged.
 
  vim:tw=78:ts=8:ft=help:norl: