refactor(types): more fixes (2)

1 files changed, 42 insertions, 35 deletions

diff --git a/runtime/lua/vim/lsp/handlers.lua b/runtime/lua/vim/lsp/handlers.lua
index d816fb1482..daf4fec8d2 100644
--- a/runtime/lua/vim/lsp/handlers.lua
+++ b/runtime/lua/vim/lsp/handlers.lua
@@ -16,12 +16,12 @@ local function err_message(...)
   api.nvim_command('redraw')
 end
 
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_executeCommand
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_executeCommand
 M[ms.workspace_executeCommand] = function(_, _, _, _)
   -- Error handling is done implicitly by wrapping all handlers; see end of this file
 end
 
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#progress
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#progress
 ---@param result lsp.ProgressParams
 ---@param ctx lsp.HandlerContext
 M[ms.dollar_progress] = function(_, result, ctx)
@@ -57,7 +57,7 @@ M[ms.dollar_progress] = function(_, result, ctx)
   })
 end
 
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#window_workDoneProgress_create
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#window_workDoneProgress_create
 ---@param result lsp.WorkDoneProgressCreateParams
 ---@param ctx lsp.HandlerContext
 M[ms.window_workDoneProgress_create] = function(_, result, ctx)
@@ -70,7 +70,7 @@ M[ms.window_workDoneProgress_create] = function(_, result, ctx)
   return vim.NIL
 end
 
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#window_showMessageRequest
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#window_showMessageRequest
 ---@param result lsp.ShowMessageRequestParams
 M[ms.window_showMessageRequest] = function(_, result)
   local actions = result.actions or {}
@@ -106,7 +106,8 @@ M[ms.window_showMessageRequest] = function(_, result)
   end
 end
 
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#client_registerCapability
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#client_registerCapability
+--- @param result lsp.RegistrationParams
 M[ms.client_registerCapability] = function(_, result, ctx)
   local client_id = ctx.client_id
   local client = assert(vim.lsp.get_client_by_id(client_id))
@@ -136,7 +137,8 @@ M[ms.client_registerCapability] = function(_, result, ctx)
   return vim.NIL
 end
 
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#client_unregisterCapability
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#client_unregisterCapability
+--- @param result lsp.UnregistrationParams
 M[ms.client_unregisterCapability] = function(_, result, ctx)
   local client_id = ctx.client_id
   local client = assert(vim.lsp.get_client_by_id(client_id))
@@ -150,7 +152,7 @@ M[ms.client_unregisterCapability] = function(_, result, ctx)
   return vim.NIL
 end
 
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_applyEdit
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_applyEdit
 M[ms.workspace_applyEdit] = function(_, workspace_edit, ctx)
   assert(
     workspace_edit,
@@ -178,7 +180,8 @@ local function lookup_section(table, section)
   return vim.tbl_get(table, unpack(keys))
 end
 
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_configuration
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_configuration
+--- @param result lsp.ConfigurationParams
 M[ms.workspace_configuration] = function(_, result, ctx)
   local client_id = ctx.client_id
   local client = vim.lsp.get_client_by_id(client_id)
@@ -211,7 +214,7 @@ M[ms.workspace_configuration] = function(_, result, ctx)
   return response
 end
 
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_workspaceFolders
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_workspaceFolders
 M[ms.workspace_workspaceFolders] = function(_, _, ctx)
   local client_id = ctx.client_id
   local client = vim.lsp.get_client_by_id(client_id)
@@ -238,7 +241,7 @@ M[ms.textDocument_inlayHint] = function(...)
   return vim.lsp.inlay_hint.on_inlayhint(...)
 end
 
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_references
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_references
 M[ms.textDocument_references] = function(_, result, ctx, config)
   if not result or vim.tbl_isempty(result) then
     vim.notify('No references found')
@@ -296,7 +299,7 @@ local function response_to_list(map_result, entity, title_fn)
   end
 end
 
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_documentSymbol
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_documentSymbol
 M[ms.textDocument_documentSymbol] = response_to_list(
   util.symbols_to_items,
   'document symbols',
@@ -306,12 +309,12 @@ M[ms.textDocument_documentSymbol] = response_to_list(
   end
 )
 
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_symbol
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_symbol
 M[ms.workspace_symbol] = response_to_list(util.symbols_to_items, 'symbols', function(ctx)
   return string.format("Symbols matching '%s'", ctx.params.query)
 end)
 
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_rename
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_rename
 M[ms.textDocument_rename] = function(_, result, ctx, _)
   if not result then
     vim.notify("Language server couldn't provide rename result", vim.log.levels.INFO)
@@ -321,7 +324,7 @@ M[ms.textDocument_rename] = function(_, result, ctx, _)
   util.apply_workspace_edit(result, client.offset_encoding)
 end
 
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_rangeFormatting
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_rangeFormatting
 M[ms.textDocument_rangeFormatting] = function(_, result, ctx, _)
   if not result then
     return
@@ -330,7 +333,7 @@ M[ms.textDocument_rangeFormatting] = function(_, result, ctx, _)
   util.apply_text_edits(result, ctx.bufnr, client.offset_encoding)
 end
 
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_formatting
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_formatting
 M[ms.textDocument_formatting] = function(_, result, ctx, _)
   if not result then
     return
@@ -339,7 +342,7 @@ M[ms.textDocument_formatting] = function(_, result, ctx, _)
   util.apply_text_edits(result, ctx.bufnr, client.offset_encoding)
 end
 
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_completion
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_completion
 M[ms.textDocument_completion] = function(_, result, _, _)
   if vim.tbl_isempty(result or {}) then
     return
@@ -405,14 +408,14 @@ function M.hover(_, result, ctx, config)
   return util.open_floating_preview(contents, format, config)
 end
 
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover
 M[ms.textDocument_hover] = M.hover
 
 --- Jumps to a location. Used as a handler for multiple LSP methods.
 ---@param _ nil not used
 ---@param result (table) result of LSP method; a location or a list of locations.
 ---@param ctx (lsp.HandlerContext) table containing the context of the request, including the method
----@param config? vim.lsp.buf.LocationOpts
+---@param config? vim.lsp.LocationOpts
 ---(`textDocument/definition` can return `Location` or `Location[]`
 local function location_handler(_, result, ctx, config)
   if result == nil or vim.tbl_isempty(result) then
@@ -445,13 +448,13 @@ local function location_handler(_, result, ctx, config)
   api.nvim_command('botright copen')
 end
 
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_declaration
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_declaration
 M[ms.textDocument_declaration] = location_handler
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_definition
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_definition
 M[ms.textDocument_definition] = location_handler
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_typeDefinition
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_typeDefinition
 M[ms.textDocument_typeDefinition] = location_handler
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_implementation
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_implementation
 M[ms.textDocument_implementation] = location_handler
 
 --- |lsp-handler| for the method "textDocument/signatureHelp".
@@ -509,10 +512,10 @@ function M.signature_help(_, result, ctx, config)
   return fbuf, fwin
 end
 
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_signatureHelp
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_signatureHelp
 M[ms.textDocument_signatureHelp] = M.signature_help
 
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_documentHighlight
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_documentHighlight
 M[ms.textDocument_documentHighlight] = function(_, result, ctx, _)
   if not result then
     return
@@ -525,21 +528,22 @@ M[ms.textDocument_documentHighlight] = function(_, result, ctx, _)
   util.buf_highlight_references(ctx.bufnr, result, client.offset_encoding)
 end
 
----@private
+--- @private
 ---
 --- Displays call hierarchy in the quickfix window.
 ---
----@param direction 'from'|'to' `"from"` for incoming calls and `"to"` for outgoing calls
----@return function
---- `CallHierarchyIncomingCall[]` if {direction} is `"from"`,
---- `CallHierarchyOutgoingCall[]` if {direction} is `"to"`,
-local make_call_hierarchy_handler = function(direction)
+--- @param direction 'from'|'to' `"from"` for incoming calls and `"to"` for outgoing calls
+--- @overload fun(direction:'from'): fun(_, result: lsp.CallHierarchyIncomingCall[]?)
+--- @overload fun(direction:'to'): fun(_, result: lsp.CallHierarchyOutgoingCall[]?)
+local function make_call_hierarchy_handler(direction)
+  --- @param result lsp.CallHierarchyIncomingCall[]|lsp.CallHierarchyOutgoingCall[]
   return function(_, result)
     if not result then
       return
     end
     local items = {}
     for _, call_hierarchy_call in pairs(result) do
+      --- @type lsp.CallHierarchyItem
       local call_hierarchy_item = call_hierarchy_call[direction]
       for _, range in pairs(call_hierarchy_call.fromRanges) do
         table.insert(items, {
@@ -555,13 +559,14 @@ local make_call_hierarchy_handler = function(direction)
   end
 end
 
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#callHierarchy_incomingCalls
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#callHierarchy_incomingCalls
 M[ms.callHierarchy_incomingCalls] = make_call_hierarchy_handler('from')
 
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#callHierarchy_outgoingCalls
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#callHierarchy_outgoingCalls
 M[ms.callHierarchy_outgoingCalls] = make_call_hierarchy_handler('to')
 
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#window_logMessage
+--- @see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#window_logMessage
+--- @param result lsp.LogMessageParams
 M[ms.window_logMessage] = function(_, result, ctx, _)
   local message_type = result.type
   local message = result.message
@@ -583,7 +588,8 @@ M[ms.window_logMessage] = function(_, result, ctx, _)
   return result
 end
 
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#window_showMessage
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#window_showMessage
+--- @param result lsp.ShowMessageParams
 M[ms.window_showMessage] = function(_, result, ctx, _)
   local message_type = result.type
   local message = result.message
@@ -602,7 +608,8 @@ M[ms.window_showMessage] = function(_, result, ctx, _)
   return result
 end
 
---see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#window_showDocument
+--- @see # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#window_showDocument
+--- @param result lsp.ShowDocumentParams
 M[ms.window_showDocument] = function(_, result, ctx, _)
   local uri = result.uri