Add docs for most vim.lsp methods

Most of the lsp.log will be addressed in a separate PR.

runtime/lua/vim/lsp/buf.lua

@@ -7,14 +7,41 @@ local list_extend = vim.list_extend
 
 local M = {}
 
+--@private
+--- Returns nil if {status} is false or nil, otherwise returns the rest of the
+--- arguments.
 local function ok_or_nil(status, ...)
   if not status then return end
   return ...
 end
+
+--@private
+--- Swallows errors.
+---
+--@param fn Function to run
+--@param ... Function arguments
+--@returns Result of `fn(...)` if there are no errors, otherwise nil.
+--- Returns nil if errors occur during {fn}, otherwise returns
 local function npcall(fn, ...)
   return ok_or_nil(pcall(fn, ...))
 end
 
+--@private
+--- Sends an async request to all active clients attached to the current
+--- buffer.
+---
+--@param method (string) LSP method name
+--@param params (optional, table) Parameters to send to the server
+--@param callback (optional, functionnil) Handler
+--  `function(err, method, params, client_id)` for this request. Defaults
+--  to the client callback in `client.callbacks`. See |lsp-callbacks|.
+--
+--@returns 2-tuple:
+---  - Map of client-id:request-id pairs for all successful requests.
+---  - Function which can be used to cancel all the requests. You could instead
+---    iterate all clients and call their `cancel_request()` methods.
+---
+--@see |vim.lsp.buf_request()|
 local function request(method, params, callback)
   validate {
     method = {method, 's'};
@@ -23,9 +50,10 @@ local function request(method, params, callback)
   return vim.lsp.buf_request(0, method, params, callback)
 end
 
---- Sends a notification through all clients associated with current buffer.
---
---@return `true` if server responds.
+--- Checks whether the language servers attached to the current buffer are
+--- ready.
+---
+--@returns `true` if server responds.
 function M.server_ready()
   return not not vim.lsp.buf_notify(0, "window/progress", {})
 end
@@ -74,6 +102,12 @@ end
 
 --- Retrieves the completion items at the current cursor position. Can only be
 --- called in Insert mode.
+---
+--@param 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 |vim.lsp.protocol.constants.CompletionTriggerKind|
 function M.completion(context)
   local params = util.make_position_params()
   params.context = context
@@ -82,20 +116,27 @@ end
 
 --- 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.
+--@param options (optional, table) Can be used to specify FormattingOptions.
 --- Some unspecified options will be automatically derived from the current
 --- Neovim options.
+--
+--@see https://microsoft.github.io/language-server-protocol/specification#textDocument_formatting
 function M.formatting(options)
   local params = util.make_formatting_params(options)
   return request('textDocument/formatting', params)
 end
 
---- Perform |vim.lsp.buf.formatting()| synchronously.
+--- Performs |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()|.
+--- saved. {timeout_ms} is passed on to |vim.lsp.buf_request_sync()|. Example:
+---
+--- <pre>
+--- vim.api.nvim_command[[autocmd BufWritePre <buffer> lua vim.lsp.buf.formatting_sync()]]
+--- </pre>
+---
+--@param options Table with valid `FormattingOptions` entries
+--@param timeout_ms (number) Request timeout
 function M.formatting_sync(options, timeout_ms)
   local params = util.make_formatting_params(options)
   local result = vim.lsp.buf_request_sync(0, "textDocument/formatting", params, timeout_ms)
@@ -104,6 +145,13 @@ function M.formatting_sync(options, timeout_ms)
   vim.lsp.util.apply_text_edits(result)
 end
 
+--- Formats a given range.
+---
+--@param options Table with valid `FormattingOptions` entries.
+--@param start_pos ({number, number}, optional) mark-indexed position.
+---Defaults to the start of the last visual selection.
+--@param start_pos ({number, number}, optional) mark-indexed position.
+---Defaults to the end of the last visual selection.
 function M.range_formatting(options, start_pos, end_pos)
   validate {
     options = {options, 't', true};
@@ -138,8 +186,10 @@ function M.range_formatting(options, start_pos, end_pos)
   return request('textDocument/rangeFormatting', params)
 end
 
---- 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.
+---
+--@param new_name (string) If not provided, the user will be prompted for a new
+---name using |input()|.
 function M.rename(new_name)
   -- TODO(ashkan) use prepareRename
   -- * result: [`Range`](#range) \| `{ range: Range, placeholder: string }` \| `null` describing the range of the string to rename and optionally a placeholder text of the string content to be renamed. If `null` is returned then it is deemed that a 'textDocument/rename' request is not valid at the given position.
@@ -152,6 +202,8 @@ end
 
 --- Lists all the references to the symbol under the cursor in the quickfix window.
 ---
+--@param context (table) Context for the request
+--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_references
 function M.references(context)
   validate { context = { context, 't', true } }
   local params = util.make_position_params()
@@ -169,6 +221,7 @@ function M.document_symbol()
   request('textDocument/documentSymbol', params)
 end
 
+--@private
 local function pick_call_hierarchy_item(call_hierarchy_items)
   if not call_hierarchy_items then return end
   if #call_hierarchy_items == 1 then
@@ -186,6 +239,9 @@ local function pick_call_hierarchy_item(call_hierarchy_items)
   return choice
 end
 
+--- 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|.
 function M.incoming_calls()
   local params = util.make_position_params()
   request('textDocument/prepareCallHierarchy', params, function(_, _, result)
@@ -194,6 +250,9 @@ function M.incoming_calls()
   end)
 end
 
+--- 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|.
 function M.outgoing_calls()
   local params = util.make_position_params()
   request('textDocument/prepareCallHierarchy', params, function(_, _, result)
@@ -204,9 +263,11 @@ end
 
 --- 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.
+---
+--@param query (string, optional)
 function M.workspace_symbol(query)
   query = query or npcall(vfn.input, "Query: ")
   local params = {query = query}
@@ -227,10 +288,17 @@ function M.document_highlight()
   request('textDocument/documentHighlight', params)
 end
 
+--- Removes document highlights from current buffer.
+---
 function M.clear_references()
   util.buf_clear_references()
 end
 
+--- Selects a code action from the input list that is available at the current
+--- cursor position.
+--
+--@param context: (table, optional) Valid `CodeActionContext` object
+--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeAction
 function M.code_action(context)
   validate { context = { context, 't', true } }
   context = context or { diagnostics = util.get_line_diagnostics() }
@@ -239,6 +307,10 @@ function M.code_action(context)
   request('textDocument/codeAction', params)
 end
 
+--- Executes an LSP server command.
+---
+--@param command A valid `ExecuteCommandParams` object
+--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_executeCommand
 function M.execute_command(command)
   validate {
     command = { command.command, 's' },