Add docs for most vim.lsp methods

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

1 files changed, 45 insertions, 2 deletions

diff --git a/runtime/lua/vim/lsp/callbacks.lua b/runtime/lua/vim/lsp/callbacks.lua
index 1ed58995d0..9920af0124 100644
--- a/runtime/lua/vim/lsp/callbacks.lua
+++ b/runtime/lua/vim/lsp/callbacks.lua
@@ -7,17 +7,22 @@ local buf = require 'vim.lsp.buf'
 
 local M = {}
 
+--@private
+--- Writes to error buffer.
+--@param ... (table of strings) Will be concatenated before being written
 local function err_message(...)
   api.nvim_err_writeln(table.concat(vim.tbl_flatten{...}))
   api.nvim_command("redraw")
 end
 
+--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_executeCommand
 M['workspace/executeCommand'] = function(err, _)
   if err then
     error("Could not execute code action: "..err.message)
   end
 end
 
+--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeAction
 M['textDocument/codeAction'] = function(_, _, actions)
   if actions == nil or vim.tbl_isempty(actions) then
     print("No code actions available")
@@ -51,6 +56,7 @@ M['textDocument/codeAction'] = function(_, _, actions)
   end
 end
 
+--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_applyEdit
 M['workspace/applyEdit'] = function(_, _, workspace_edit)
   if not workspace_edit then return end
   -- TODO(ashkan) Do something more with label?
@@ -64,6 +70,7 @@ M['workspace/applyEdit'] = function(_, _, workspace_edit)
   }
 end
 
+--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_publishDiagnostics
 M['textDocument/publishDiagnostics'] = function(_, _, result)
   if not result then return end
   local uri = result.uri
@@ -102,6 +109,7 @@ M['textDocument/publishDiagnostics'] = function(_, _, result)
   vim.api.nvim_command("doautocmd User LspDiagnosticsChanged")
 end
 
+--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_references
 M['textDocument/references'] = function(_, _, result)
   if not result then return end
   util.set_qflist(util.locations_to_items(result))
@@ -109,6 +117,13 @@ M['textDocument/references'] = function(_, _, result)
   api.nvim_command("wincmd p")
 end
 
+--@private
+--- Prints given list of symbols to the quickfix list.
+--@param _ (not used)
+--@param _ (not used)
+--@param result (list of Symbols) LSP method name
+--@param result (table) result of LSP method; a location or a list of locations.
+---(`textDocument/definition` can return `Location` or `Location[]`
 local symbol_callback = function(_, _, result, _, bufnr)
   if not result or vim.tbl_isempty(result) then return end
 
@@ -116,24 +131,30 @@ local symbol_callback = function(_, _, result, _, bufnr)
   api.nvim_command("copen")
   api.nvim_command("wincmd p")
 end
+--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_documentSymbol
 M['textDocument/documentSymbol'] = symbol_callback
+--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_symbol
 M['workspace/symbol'] = symbol_callback
 
+--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_rename
 M['textDocument/rename'] = function(_, _, result)
   if not result then return end
   util.apply_workspace_edit(result)
 end
 
+--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_rangeFormatting
 M['textDocument/rangeFormatting'] = function(_, _, result)
   if not result then return end
   util.apply_text_edits(result)
 end
 
+--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_formatting
 M['textDocument/formatting'] = function(_, _, result)
   if not result then return end
   util.apply_text_edits(result)
 end
 
+--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_completion
 M['textDocument/completion'] = function(_, _, result)
   if vim.tbl_isempty(result or {}) then return end
   local row, col = unpack(api.nvim_win_get_cursor(0))
@@ -146,6 +167,7 @@ M['textDocument/completion'] = function(_, _, result)
   vim.fn.complete(textMatch+1, matches)
 end
 
+--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover
 M['textDocument/hover'] = function(_, method, result)
   util.focusable_float(method, function()
     if not (result and result.contents) then
@@ -166,6 +188,12 @@ M['textDocument/hover'] = function(_, method, result)
   end)
 end
 
+--@private
+--- Jumps to a location. Used as a callback for multiple LSP methods.
+--@param _ (not used)
+--@param method (string) LSP method name
+--@param result (table) result of LSP method; a location or a list of locations.
+---(`textDocument/definition` can return `Location` or `Location[]`
 local function location_callback(_, method, result)
   if result == nil or vim.tbl_isempty(result) then
     local _ = log.info() and log.info(method, 'No location found')
@@ -188,11 +216,16 @@ local function location_callback(_, method, result)
   end
 end
 
+--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_declaration
 M['textDocument/declaration'] = location_callback
+--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_definition
 M['textDocument/definition'] = location_callback
+--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_typeDefinition
 M['textDocument/typeDefinition'] = location_callback
+--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_implementation
 M['textDocument/implementation'] = location_callback
 
+--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_signatureHelp
 M['textDocument/signatureHelp'] = function(_, method, result)
   util.focusable_preview(method, function()
     if not (result and result.signatures and result.signatures[1]) then
@@ -208,15 +241,21 @@ M['textDocument/signatureHelp'] = function(_, method, result)
   end)
 end
 
+--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_documentHighlight
 M['textDocument/documentHighlight'] = function(_, _, result, _)
   if not result then return end
   local bufnr = api.nvim_get_current_buf()
   util.buf_highlight_references(bufnr, result)
 end
 
--- direction is "from" for incoming calls and "to" for outgoing calls
+--@private
+---
+--- Displays call hierarchy in the quickfix window.
+---
+--@param direction `"from"` for incoming calls and `"to"` for outgoing calls
+--@returns `CallHierarchyIncomingCall[]` if {direction} is `"from"`,
+--@returns `CallHierarchyOutgoingCall[]` if {direction} is `"to"`,
 local make_call_hierarchy_callback = function(direction)
-  -- result is a CallHierarchy{Incoming,Outgoing}Call[]
   return function(_, _, result)
     if not result then return end
     local items = {}
@@ -237,10 +276,13 @@ local make_call_hierarchy_callback = function(direction)
   end
 end
 
+--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#callHierarchy/incomingCalls
 M['callHierarchy/incomingCalls'] = make_call_hierarchy_callback('from')
 
+--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#callHierarchy/outgoingCalls
 M['callHierarchy/outgoingCalls'] = make_call_hierarchy_callback('to')
 
+--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#window/logMessage
 M['window/logMessage'] = function(_, _, result, client_id)
   local message_type = result.type
   local message = result.message
@@ -261,6 +303,7 @@ M['window/logMessage'] = function(_, _, result, client_id)
   return result
 end
 
+--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#window/showMessage
 M['window/showMessage'] = function(_, _, result, client_id)
   local message_type = result.type
   local message = result.message