refactor(types): more fixes (2)

2024-12-20 03:05:11 -07:00 · 2024-03-06 12:15:25 +00:00 · 2024-03-06 12:15:25 +00:00 · 85b13751a5
commit 85b13751a5
parent 3c572a31a3
11 changed files with 110 additions and 95 deletions
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@ -1403,6 +1403,7 @@ rename({new_name}, {options})                           *vim.lsp.buf.rename()*
                      predicate are included.
                    • {name}? (`string`) Restrict clients used for rename to
                      ones where client.name matches this field.
+                    • {bufnr}? (`integer`) (default: current buffer)

 signature_help()                                *vim.lsp.buf.signature_help()*
    Displays signature information about the symbol under the cursor in a
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@ -3774,7 +3774,7 @@ vim.version.range({spec})                                *vim.version.range()*
      • {spec}  (`string`) Version range "spec"

    Return: ~
-        (`table`) A table with the following fields:
+        (`table?`) A table with the following fields:
        • {from} (`vim.Version`)
        • {to}? (`vim.Version`)
        • {has} (`fun(self: vim.VersionRangeversion: string|vim.Version)`)
--- a/runtime/lua/tohtml.lua
+++ b/runtime/lua/tohtml.lua
@ -431,13 +431,13 @@ local function styletable_treesitter(state)
  end
  buf_highlighter.tree:parse(true)
  buf_highlighter.tree:for_each_tree(function(tstree, tree)
-    --- @cast tree LanguageTree
+    --- @cast tree vim.treesitter.LanguageTree
    if not tstree then
      return
    end
    local root = tstree:root()
    local q = buf_highlighter:get_query(tree:lang())
-    --- @type Query?
+    --- @type vim.treesitter.Query?
    local query = q:query()
    if not query then
      return
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@ -64,6 +64,9 @@
 --- In addition to the |vim.iter()| function, the |vim.iter| module provides
 --- convenience functions like |vim.iter.filter()| and |vim.iter.totable()|.

+--- LuaLS is bad at generics which this module mostly deals with
+--- @diagnostic disable:no-unknown
+
 ---@nodoc
 ---@class IterMod
 ---@operator call:Iter
@ -189,7 +192,7 @@ end
 ---                       in the pipeline and returns false or nil if the
 ---                       current iterator element should be removed.
 ---@return Iter
-function Iter.filter(self, f)
+function Iter:filter(f)
  return self:map(function(...)
    if f(...) then
      return ...
@ -198,7 +201,7 @@ function Iter.filter(self, f)
 end

 ---@private
-function ListIter.filter(self, f)
+function ListIter:filter(f)
  local inc = self._head < self._tail and 1 or -1
  local n = self._head
  for i = self._head, self._tail - inc, inc do
@ -231,12 +234,13 @@ end
 ---@param depth? number Depth to which |list-iterator| should be flattened
 ---                        (defaults to 1)
 ---@return Iter
-function Iter.flatten(self, depth) -- luacheck: no unused args
+---@diagnostic disable-next-line:unused-local
+function Iter:flatten(depth) -- luacheck: no unused args
  error('flatten() requires a list-like table')
 end

 ---@private
-function ListIter.flatten(self, depth)
+function ListIter:flatten(depth)
  depth = depth or 1
  local inc = self._head < self._tail and 1 or -1
  local target = {}
@ -282,7 +286,7 @@ end
 ---                      in the next pipeline stage. Nil return values
 ---                      are filtered from the output.
 ---@return Iter
-function Iter.map(self, f)
+function Iter:map(f)
  -- Implementation note: the reader may be forgiven for observing that this
  -- function appears excessively convoluted. The problem to solve is that each
  -- stage of the iterator pipeline can return any number of values, and the
@ -326,7 +330,7 @@ function Iter.map(self, f)
 end

 ---@private
-function ListIter.map(self, f)
+function ListIter:map(f)
  local inc = self._head < self._tail and 1 or -1
  local n = self._head
  for i = self._head, self._tail - inc, inc do
@ -347,7 +351,7 @@ end
 ---@param f fun(...) Function to execute for each item in the pipeline.
 ---                  Takes all of the values returned by the previous stage
 ---                  in the pipeline as arguments.
-function Iter.each(self, f)
+function Iter:each(f)
  local function fn(...)
    if select(1, ...) ~= nil then
      f(...)
@ -359,7 +363,7 @@ function Iter.each(self, f)
 end

 ---@private
-function ListIter.each(self, f)
+function ListIter:each(f)
  local inc = self._head < self._tail and 1 or -1
  for i = self._head, self._tail - inc, inc do
    f(unpack(self._table[i]))
@ -392,7 +396,7 @@ end
 ---
 ---
 ---@return table
-function Iter.totable(self)
+function Iter:totable()
  local t = {}

  while true do
@ -407,7 +411,7 @@ function Iter.totable(self)
 end

 ---@private
-function ListIter.totable(self)
+function ListIter:totable()
  if self.next ~= ListIter.next or self._head >= self._tail then
    return Iter.totable(self)
  end
@ -445,7 +449,7 @@ end
 ---
 --- @param delim string Delimiter
 --- @return string
-function Iter.join(self, delim)
+function Iter:join(delim)
  return table.concat(self:totable(), delim)
 end

@ -470,7 +474,7 @@ end
 ---@param init A Initial value of the accumulator.
 ---@param f fun(acc:A, ...):A Accumulation function.
 ---@return A
-function Iter.fold(self, init, f)
+function Iter:fold(init, f)
  local acc = init

  --- Use a closure to handle var args returned from iterator
@ -487,7 +491,7 @@ function Iter.fold(self, init, f)
 end

 ---@private
-function ListIter.fold(self, init, f)
+function ListIter:fold(init, f)
  local acc = init
  local inc = self._head < self._tail and 1 or -1
  for i = self._head, self._tail - inc, inc do
@ -513,14 +517,13 @@ end
 --- ```
 ---
 ---@return any
---@diagnostic disable-next-line: unused-local
-function Iter.next(self) -- luacheck: no unused args
+function Iter:next()
  -- This function is provided by the source iterator in Iter.new. This definition exists only for
  -- the docstring
 end

 ---@private
-function ListIter.next(self)
+function ListIter:next()
  if self._head ~= self._tail then
    local v = self._table[self._head]
    local inc = self._head < self._tail and 1 or -1
@ -542,12 +545,12 @@ end
 --- ```
 ---
 ---@return Iter
-function Iter.rev(self) -- luacheck: no unused args
+function Iter:rev()
  error('rev() requires a list-like table')
 end

 ---@private
-function ListIter.rev(self)
+function ListIter:rev()
  local inc = self._head < self._tail and 1 or -1
  self._head, self._tail = self._tail - inc, self._head - inc
  return self
@ -570,13 +573,12 @@ end
 --- ```
 ---
 ---@return any
---@diagnostic disable-next-line: unused-local
-function Iter.peek(self) -- luacheck: no unused args
+function Iter:peek()
  error('peek() requires a list-like table')
 end

 ---@private
-function ListIter.peek(self)
+function ListIter:peek()
  if self._head ~= self._tail then
    return self._table[self._head]
  end
@ -605,7 +607,7 @@ end
 --- ```
 ---@param f any
 ---@return any
-function Iter.find(self, f)
+function Iter:find(f)
  if type(f) ~= 'function' then
    local val = f
    f = function(v)
@ -652,12 +654,12 @@ end
 ---@param f any
 ---@return any
 ---@diagnostic disable-next-line: unused-local
-function Iter.rfind(self, f) -- luacheck: no unused args
+function Iter:rfind(f) -- luacheck: no unused args
  error('rfind() requires a list-like table')
 end

 ---@private
-function ListIter.rfind(self, f)
+function ListIter:rfind(f)
  if type(f) ~= 'function' then
    local val = f
    f = function(v)
@ -692,7 +694,7 @@ end
 ---
 ---@param n integer
 ---@return Iter
-function Iter.take(self, n)
+function Iter:take(n)
  local next = self.next
  local i = 0
  self.next = function()
@ -705,7 +707,7 @@ function Iter.take(self, n)
 end

 ---@private
-function ListIter.take(self, n)
+function ListIter:take(n)
  local inc = self._head < self._tail and 1 or -1
  self._tail = math.min(self._tail, self._head + n * inc)
  return self
@ -724,13 +726,12 @@ end
 --- ```
 ---
 ---@return any
---@diagnostic disable-next-line: unused-local
-function Iter.nextback(self) -- luacheck: no unused args
+function Iter:nextback()
  error('nextback() requires a list-like table')
 end

 --- @nodoc
-function ListIter.nextback(self)
+function ListIter:nextback()
  if self._head ~= self._tail then
    local inc = self._head < self._tail and 1 or -1
    self._tail = self._tail - inc
@ -755,13 +756,12 @@ end
 --- ```
 ---
 ---@return any
---@diagnostic disable-next-line: unused-local
-function Iter.peekback(self) -- luacheck: no unused args
+function Iter:peekback()
  error('peekback() requires a list-like table')
 end

 ---@nodoc
-function ListIter.peekback(self)
+function ListIter:peekback()
  if self._head ~= self._tail then
    local inc = self._head < self._tail and 1 or -1
    return self._table[self._tail - inc]
@ -782,7 +782,7 @@ end
 ---
 ---@param n number Number of values to skip.
 ---@return Iter
-function Iter.skip(self, n)
+function Iter:skip(n)
  for _ = 1, n do
    local _ = self:next()
  end
@ -790,7 +790,7 @@ function Iter.skip(self, n)
 end

 ---@private
-function ListIter.skip(self, n)
+function ListIter:skip(n)
  local inc = self._head < self._tail and n or -n
  self._head = self._head + inc
  if (inc > 0 and self._head > self._tail) or (inc < 0 and self._head < self._tail) then
@ -814,12 +814,12 @@ end
 ---@param n number Number of values to skip.
 ---@return Iter
 ---@diagnostic disable-next-line: unused-local
-function Iter.skipback(self, n) -- luacheck: no unused args
+function Iter:skipback(n) -- luacheck: no unused args
  error('skipback() requires a list-like table')
 end

 ---@private
-function ListIter.skipback(self, n)
+function ListIter:skipback(n)
  local inc = self._head < self._tail and n or -n
  self._tail = self._tail - inc
  if (inc > 0 and self._head > self._tail) or (inc < 0 and self._head < self._tail) then
@ -844,7 +844,7 @@ end
 ---
 ---@param n number The index of the value to return.
 ---@return any
-function Iter.nth(self, n)
+function Iter:nth(n)
  if n > 0 then
    return self:skip(n - 1):next()
  end
@ -866,7 +866,7 @@ end
 ---
 ---@param n number The index of the value to return.
 ---@return any
-function Iter.nthback(self, n)
+function Iter:nthback(n)
  if n > 0 then
    return self:skipback(n - 1):nextback()
  end
@ -880,12 +880,12 @@ end
 ---@param last number
 ---@return Iter
 ---@diagnostic disable-next-line: unused-local
-function Iter.slice(self, first, last) -- luacheck: no unused args
+function Iter:slice(first, last) -- luacheck: no unused args
  error('slice() requires a list-like table')
 end

 ---@private
-function ListIter.slice(self, first, last)
+function ListIter:slice(first, last)
  return self:skip(math.max(0, first - 1)):skipback(math.max(0, self._tail - last - 1))
 end

@ -894,7 +894,7 @@ end
 ---@param pred fun(...):boolean Predicate function. Takes all values returned from the previous
 ---                          stage in the pipeline as arguments and returns true if the
 ---                          predicate matches.
-function Iter.any(self, pred)
+function Iter:any(pred)
  local any = false

  --- Use a closure to handle var args returned from iterator
@ -918,7 +918,7 @@ end
 ---@param pred fun(...):boolean Predicate function. Takes all values returned from the previous
 ---                          stage in the pipeline as arguments and returns true if the
 ---                          predicate matches.
-function Iter.all(self, pred)
+function Iter:all(pred)
  local all = true

  local function fn(...)
@ -953,7 +953,7 @@ end
 --- ```
 ---
 ---@return any
-function Iter.last(self)
+function Iter:last()
  local last = self:next()
  local cur = self:next()
  while cur do
@ -964,7 +964,7 @@ function Iter.last(self)
 end

 ---@private
-function ListIter.last(self)
+function ListIter:last()
  local inc = self._head < self._tail and 1 or -1
  local v = self._table[self._tail - inc]
  self._head = self._tail
@ -1000,7 +1000,7 @@ end
 --- ```
 ---
 ---@return Iter
-function Iter.enumerate(self)
+function Iter:enumerate()
  local i = 0
  return self:map(function(...)
    i = i + 1
@ -1009,7 +1009,7 @@ function Iter.enumerate(self)
 end

 ---@private
-function ListIter.enumerate(self)
+function ListIter:enumerate()
  local inc = self._head < self._tail and 1 or -1
  for i = self._head, self._tail - inc, inc do
    local v = self._table[i]
--- a/runtime/lua/vim/lsp/_dynamic.lua
+++ b/runtime/lua/vim/lsp/_dynamic.lua
@ -58,7 +58,7 @@ end
 --- @param method string
 --- @param opts? {bufnr: integer?}
 --- @return lsp.Registration? (table|nil) the registration if found
--- @private
+--- @package
 function M:get(method, opts)
  opts = opts or {}
  opts.bufnr = opts.bufnr or vim.api.nvim_get_current_buf()
--- a/runtime/lua/vim/lsp/buf.lua
+++ b/runtime/lua/vim/lsp/buf.lua
@ -248,6 +248,9 @@ function M.format(options)
    vim.notify('[LSP] Format request failed, no matching language servers.')
  end

+  --- @param client vim.lsp.Client
+  --- @param params lsp.DocumentFormattingParams
+  --- @return lsp.DocumentFormattingParams
  local function set_range(client, params)
    if range then
      local range_params =
@ -294,6 +297,9 @@ end
 --- Restrict clients used for rename to ones where client.name matches
 --- this field.
 --- @field name? string
+---
+--- (default: current buffer)
+--- @field bufnr? integer

 --- Renames all references to the symbol under the cursor.
 ---
@ -786,6 +792,7 @@ function M.code_action(options)
  options = options or {}
  -- Detect old API call code_action(context) which should now be
  -- code_action({ context = context} )
+  --- @diagnostic disable-next-line:undefined-field
  if options.diagnostics or options.only then
    options = { options = options }
  end
--- 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
@ -530,16 +533,17 @@ end
 --- 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)
+--- @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

--- a/runtime/lua/vim/treesitter/_meta.lua
+++ b/runtime/lua/vim/treesitter/_meta.lua
@ -39,7 +39,7 @@ local TSNode = {}
 ---@param start? integer
 ---@param end_? integer
 ---@param opts? table
---@return fun(): integer, TSNode, TSMatch
+---@return fun(): integer, TSNode, vim.treesitter.query.TSMatch
 function TSNode:_rawquery(query, captures, start, end_, opts) end

 ---@param query TSQuery
@ -47,14 +47,13 @@ function TSNode:_rawquery(query, captures, start, end_, opts) end
 ---@param start? integer
 ---@param end_? integer
 ---@param opts? table
---@return fun(): integer, TSMatch
+---@return fun(): integer, vim.treesitter.query.TSMatch
 function TSNode:_rawquery(query, captures, start, end_, opts) end

 ---@alias TSLoggerCallback fun(logtype: 'parse'|'lex', msg: string)

 ---@class TSParser: userdata
---@field parse fun(self: TSParser, tree: TSTree?, source: integer|string, include_bytes: true): TSTree, Range6[]
---@field parse fun(self: TSParser, tree: TSTree?, source: integer|string, include_bytes: false|nil): TSTree, Range4[]
+---@field parse fun(self: TSParser, tree: TSTree?, source: integer|string, include_bytes: boolean): TSTree, (Range4|Range6)[]
 ---@field reset fun(self: TSParser)
 ---@field included_ranges fun(self: TSParser, include_bytes: boolean?): integer[]
 ---@field set_included_ranges fun(self: TSParser, ranges: (Range6|TSNode)[])
--- a/runtime/lua/vim/treesitter/_query_linter.lua
+++ b/runtime/lua/vim/treesitter/_query_linter.lua
@ -17,7 +17,7 @@ local M = {}
 --- @field is_first_lang boolean Whether this is the first language of a linter run checking queries for multiple `langs`

 --- Adds a diagnostic for node in the query buffer
--- @param diagnostics Diagnostic[]
+--- @param diagnostics vim.Diagnostic[]
 --- @param range Range4
 --- @param lint string
 --- @param lang string?
@ -114,7 +114,7 @@ end
 --- @return vim.treesitter.ParseError?
 local parse = vim.func._memoize(hash_parse, function(node, buf, lang)
  local query_text = vim.treesitter.get_node_text(node, buf)
-  local ok, err = pcall(vim.treesitter.query.parse, lang, query_text) ---@type boolean|vim.treesitter.ParseError, string|Query
+  local ok, err = pcall(vim.treesitter.query.parse, lang, query_text) ---@type boolean|vim.treesitter.ParseError, string|vim.treesitter.Query

  if not ok and type(err) == 'string' then
    return get_error_entry(err, node)
@ -123,9 +123,9 @@ end)

 --- @param buf integer
 --- @param match vim.treesitter.query.TSMatch
--- @param query Query
+--- @param query vim.treesitter.Query
 --- @param lang_context QueryLinterLanguageContext
--- @param diagnostics Diagnostic[]
+--- @param diagnostics vim.Diagnostic[]
 local function lint_match(buf, match, query, lang_context, diagnostics)
  local lang = lang_context.lang
  local parser_info = lang_context.parser_info
--- a/runtime/lua/vim/treesitter/languagetree.lua
+++ b/runtime/lua/vim/treesitter/languagetree.lua
@ -72,7 +72,7 @@ local TSCallbackNames = {
 ---@field private _callbacks table<TSCallbackName,function[]> Callback handlers
 ---@field package _callbacks_rec table<TSCallbackName,function[]> Callback handlers (recursive)
 ---@field private _children table<string,vim.treesitter.LanguageTree> Injected languages
---@field private _injection_query Query Queries defining injected languages
+---@field private _injection_query vim.treesitter.Query Queries defining injected languages
 ---@field private _injections_processed boolean
 ---@field private _opts table Options
 ---@field private _parser TSParser Parser for language
@ -473,6 +473,7 @@ function LanguageTree:for_each_child(fn, include_self)
  end

  for _, child in pairs(self._children) do
+    --- @diagnostic disable-next-line:deprecated
    child:for_each_child(fn, true)
  end
 end
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@ -274,7 +274,7 @@ end
 --- @see # https://github.com/npm/node-semver#ranges
 ---
 --- @param spec string Version range "spec"
--- @return vim.VersionRange
+--- @return vim.VersionRange?
 function M.range(spec) -- Adapted from https://github.com/folke/lazy.nvim
  if spec == '*' or spec == '' then
    return setmetatable({ from = M.parse('0.0.0') }, { __index = VersionRange })