refactor(types): more fixes (2)

11 files changed, 110 insertions, 95 deletions

diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 31b1c412c7..aa56f8bbae 100644
--- 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
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 189c26bb7a..d187caad04 100644
--- 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)`)
diff --git a/runtime/lua/tohtml.lua b/runtime/lua/tohtml.lua
index d15412edee..68fef38c64 100644
--- 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
diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index 09de969b5b..77c8d1d170 100644
--- 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]
diff --git a/runtime/lua/vim/lsp/_dynamic.lua b/runtime/lua/vim/lsp/_dynamic.lua
index 9c2af979fa..819b03a63a 100644
--- 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()
diff --git a/runtime/lua/vim/lsp/buf.lua b/runtime/lua/vim/lsp/buf.lua
index 377c8680c7..fd78a10672 100644
--- 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
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
 
diff --git a/runtime/lua/vim/treesitter/_meta.lua b/runtime/lua/vim/treesitter/_meta.lua
index 0b285d2d7f..19d97d2820 100644
--- 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)[])
diff --git a/runtime/lua/vim/treesitter/_query_linter.lua b/runtime/lua/vim/treesitter/_query_linter.lua
index b91e8ac38d..6216d4e891 100644
--- 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
diff --git a/runtime/lua/vim/treesitter/languagetree.lua b/runtime/lua/vim/treesitter/languagetree.lua
index 2f1aa36d18..640477eed4 100644
--- 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
diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
index f97e81273e..cd8748ede7 100644
--- 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 })