fix: lua annotations

10 files changed, 113 insertions, 110 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 2909f1130f..1411ac7436 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -678,44 +678,47 @@ vim.diff({a}, {b}, {opts})                                        *vim.diff()*
     Parameters: ~
       • {a}     (`string`) First string to compare
       • {b}     (`string`) Second string to compare
-      • {opts}  (`table<string,any>`) Optional parameters:
-                • `on_hunk` (callback): Invoked for each hunk in the diff.
-                  Return a negative number to cancel the callback for any
-                  remaining hunks. Args:
-                  • `start_a` (integer): Start line of hunk in {a}.
-                  • `count_a` (integer): Hunk size in {a}.
-                  • `start_b` (integer): Start line of hunk in {b}.
-                  • `count_b` (integer): Hunk size in {b}.
-                • `result_type` (string): Form of the returned diff:
-                  • "unified": (default) String in unified format.
-                  • "indices": Array of hunk locations. Note: This option is
+      • {opts}  (`table`) Optional parameters:
+                • {on_hunk}
+                  (`fun(start_a: integer, count_a: integer, start_b: integer, count_b: integer): integer`)
+                  Invoked for each hunk in the diff. Return a negative number
+                  to cancel the callback for any remaining hunks. Arguments:
+                  • `start_a` (`integer`): Start line of hunk in {a}.
+                  • `count_a` (`integer`): Hunk size in {a}.
+                  • `start_b` (`integer`): Start line of hunk in {b}.
+                  • `count_b` (`integer`): Hunk size in {b}.
+                • {result_type} (`'unified'|'indices'`, default: `'unified'`)
+                  Form of the returned diff:
+                  • `unified`: String in unified format.
+                  • `indices`: Array of hunk locations. Note: This option is
                     ignored if `on_hunk` is used.
-                • `linematch` (boolean|integer): Run linematch on the
+                • {linematch} (`boolean|integer`) Run linematch on the
                   resulting hunks from xdiff. When integer, only hunks upto
                   this size in lines are run through linematch. Requires
                   `result_type = indices`, ignored otherwise.
-                • `algorithm` (string): Diff algorithm to use. Values:
-                  • "myers" the default algorithm
-                  • "minimal" spend extra time to generate the smallest
+                • {algorithm} (`'myers'|'minimal'|'patience'|'histogram'`,
+                  default: `'myers'`) Diff algorithm to use. Values:
+                  • `myers`: the default algorithm
+                  • `minimal`: spend extra time to generate the smallest
                     possible diff
-                  • "patience" patience diff algorithm
-                  • "histogram" histogram diff algorithm
-                • `ctxlen` (integer): Context length
-                • `interhunkctxlen` (integer): Inter hunk context length
-                • `ignore_whitespace` (boolean): Ignore whitespace
-                • `ignore_whitespace_change` (boolean): Ignore whitespace
+                  • `patience`: patience diff algorithm
+                  • `histogram`: histogram diff algorithm
+                • {ctxlen} (`integer`) Context length
+                • {interhunkctxlen} (`integer`) Inter hunk context length
+                • {ignore_whitespace} (`boolean`) Ignore whitespace
+                • {ignore_whitespace_change} (`boolean`) Ignore whitespace
                   change
-                • `ignore_whitespace_change_at_eol` (boolean) Ignore
+                • {ignore_whitespace_change_at_eol} (`boolean`) Ignore
                   whitespace change at end-of-line.
-                • `ignore_cr_at_eol` (boolean) Ignore carriage return at
+                • {ignore_cr_at_eol} (`boolean`) Ignore carriage return at
                   end-of-line
-                • `ignore_blank_lines` (boolean) Ignore blank lines
-                • `indent_heuristic` (boolean): Use the indent heuristic for
+                • {ignore_blank_lines} (`boolean`) Ignore blank lines
+                • {indent_heuristic} (`boolean`) Use the indent heuristic for
                   the internal diff library.
 
     Return: ~
-        (`string|table?`) See {opts.result_type}. `nil` if {opts.on_hunk} is
-        given.
+        (`string|integer[]`) See {opts.result_type}. `nil` if {opts.on_hunk}
+        is given.
 
 
 ==============================================================================
@@ -829,8 +832,8 @@ vim.spell.check({str})                                     *vim.spell.check()*
       • {str}  (`string`)
 
     Return: ~
-        (`{[1]: string, [2]: string, [3]: string}[]`) List of tuples with
-        three items:
+        (`{[1]: string, [2]: 'bad'|'rare'|'local'|'caps', [3]: integer}[]`)
+        List of tuples with three items:
         • The badly spelled word.
         • The type of the spelling error: "bad" spelling mistake "rare" rare
           word "local" word only valid in another region "caps" word should
@@ -911,7 +914,7 @@ vim.empty_dict()                                            *vim.empty_dict()*
     Return: ~
         (`table`)
 
-vim.iconv({str}, {from}, {to}, {opts})                           *vim.iconv()*
+vim.iconv({str}, {from}, {to})                                   *vim.iconv()*
     The result is a String, which is the text {str} converted from encoding
     {from} to encoding {to}. When the conversion fails `nil` is returned. When
     some characters could not be converted they are replaced with "?". The
@@ -920,9 +923,8 @@ vim.iconv({str}, {from}, {to}, {opts})                           *vim.iconv()*
 
     Parameters: ~
       • {str}   (`string`) Text to convert
-      • {from}  (`number`) Encoding of {str}
-      • {to}    (`number`) Target encoding
-      • {opts}  (`table<string,any>?`)
+      • {from}  (`string`) Encoding of {str}
+      • {to}    (`string`) Target encoding
 
     Return: ~
         (`string?`) Converted string if conversion succeeds, `nil` otherwise.
@@ -962,7 +964,7 @@ vim.schedule({fn})                                            *vim.schedule()*
     |textlock| or other temporary restrictions.
 
     Parameters: ~
-      • {fn}  (`function`)
+      • {fn}  (`fun()`)
 
 vim.str_byteindex({str}, {index}, {use_utf16})           *vim.str_byteindex()*
     Convert UTF-32 or UTF-16 {index} to byte index. If {use_utf16} is not
@@ -974,8 +976,8 @@ vim.str_byteindex({str}, {index}, {use_utf16})           *vim.str_byteindex()*
 
     Parameters: ~
       • {str}        (`string`)
-      • {index}      (`number`)
-      • {use_utf16}  (`any?`)
+      • {index}      (`integer`)
+      • {use_utf16}  (`boolean?`)
 
 vim.str_utf_end({str}, {index})                            *vim.str_utf_end()*
     Gets the distance (in bytes) from the last byte of the codepoint
@@ -993,10 +995,10 @@ vim.str_utf_end({str}, {index})                            *vim.str_utf_end()*
 
     Parameters: ~
       • {str}    (`string`)
-      • {index}  (`number`)
+      • {index}  (`integer`)
 
     Return: ~
-        (`number`)
+        (`integer`)
 
 vim.str_utf_pos({str})                                     *vim.str_utf_pos()*
     Gets a list of the starting byte positions of each UTF-8 codepoint in the
@@ -1008,7 +1010,7 @@ vim.str_utf_pos({str})                                     *vim.str_utf_pos()*
       • {str}  (`string`)
 
     Return: ~
-        (`table`)
+        (`integer[]`)
 
 vim.str_utf_start({str}, {index})                        *vim.str_utf_start()*
     Gets the distance (in bytes) from the starting byte of the codepoint
@@ -1029,10 +1031,10 @@ vim.str_utf_start({str}, {index})                        *vim.str_utf_start()*
 
     Parameters: ~
       • {str}    (`string`)
-      • {index}  (`number`)
+      • {index}  (`integer`)
 
     Return: ~
-        (`number`)
+        (`integer`)
 
 vim.str_utfindex({str}, {index})                          *vim.str_utfindex()*
     Convert byte index to UTF-32 and UTF-16 indices. If {index} is not
@@ -1045,7 +1047,7 @@ vim.str_utfindex({str}, {index})                          *vim.str_utfindex()*
 
     Parameters: ~
       • {str}    (`string`)
-      • {index}  (`number?`)
+      • {index}  (`integer?`)
 
     Return (multiple): ~
         (`integer`) UTF-32 index
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index 2356a0c235..67cbeda2a8 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -731,8 +731,7 @@ get_captures_at_pos({bufnr}, {row}, {col})
       • {col}    (`integer`) Position column
 
     Return: ~
-        (`table[]`) List of captures
-        `{ capture = "name", metadata = { ... } }`
+        (`{capture: string, lang: string, metadata: table}[]`)
 
 get_node({opts})                                   *vim.treesitter.get_node()*
     Returns the smallest named node at the given position
diff --git a/runtime/lua/vim/_defaults.lua b/runtime/lua/vim/_defaults.lua
index 419a29a5c6..25bef2352c 100644
--- a/runtime/lua/vim/_defaults.lua
+++ b/runtime/lua/vim/_defaults.lua
@@ -196,6 +196,7 @@ do
     group = nvim_terminal_augroup,
     desc = 'Respond to OSC foreground/background color requests',
     callback = function(args)
+      --- @type integer
       local channel = vim.bo[args.buf].channel
       if channel == 0 then
         return
@@ -270,6 +271,7 @@ if tty then
     -- Wait until Nvim is finished starting to set the option to ensure the
     -- OptionSet event fires.
     if vim.v.vim_did_enter == 1 then
+      --- @diagnostic disable-next-line:no-unknown
       vim.o[option] = value
     else
       vim.api.nvim_create_autocmd('VimEnter', {
diff --git a/runtime/lua/vim/_inspector.lua b/runtime/lua/vim/_inspector.lua
index afbd6211cd..f5d1640c82 100644
--- a/runtime/lua/vim/_inspector.lua
+++ b/runtime/lua/vim/_inspector.lua
@@ -55,8 +55,8 @@ function vim.inspect_pos(bufnr, row, col, filter)
   bufnr = bufnr == 0 and vim.api.nvim_get_current_buf() or bufnr
 
   local results = {
-    treesitter = {},
-    syntax = {},
+    treesitter = {}, --- @type table[]
+    syntax = {}, --- @type table[]
     extmarks = {},
     semantic_tokens = {},
     buffer = bufnr,
@@ -93,7 +93,7 @@ function vim.inspect_pos(bufnr, row, col, filter)
   end
 
   -- namespace id -> name map
-  local nsmap = {}
+  local nsmap = {} --- @type table<integer,string>
   for name, id in pairs(vim.api.nvim_get_namespaces()) do
     nsmap[id] = name
   end
diff --git a/runtime/lua/vim/_meta/base64.lua b/runtime/lua/vim/_meta/base64.lua
index f25b4af234..8ba59e1703 100644
--- a/runtime/lua/vim/_meta/base64.lua
+++ b/runtime/lua/vim/_meta/base64.lua
@@ -3,11 +3,11 @@
 --- Encode {str} using Base64.
 ---
 --- @param str string String to encode
---- @return string Encoded string
+--- @return string : Encoded string
 function vim.base64.encode(str) end
 
 --- Decode a Base64 encoded string.
 ---
 --- @param str string Base64 encoded string
---- @return string Decoded string
+--- @return string : Decoded string
 function vim.base64.decode(str) end
diff --git a/runtime/lua/vim/_meta/builtin.lua b/runtime/lua/vim/_meta/builtin.lua
index 20b6d9dabe..75737bd040 100644
--- a/runtime/lua/vim/_meta/builtin.lua
+++ b/runtime/lua/vim/_meta/builtin.lua
@@ -119,15 +119,15 @@ function vim.stricmp(a, b) end
 --- An {index} in the middle of a UTF-16 sequence is rounded upwards to
 --- the end of that sequence.
 --- @param str string
---- @param index number
---- @param use_utf16? any
+--- @param index integer
+--- @param use_utf16? boolean
 function vim.str_byteindex(str, index, use_utf16) end
 
 --- Gets a list of the starting byte positions of each UTF-8 codepoint in the given string.
 ---
 --- Embedded NUL bytes are treated as terminating the string.
 --- @param str string
---- @return table
+--- @return integer[]
 function vim.str_utf_pos(str) end
 
 --- Gets the distance (in bytes) from the starting byte of the codepoint (character) that {index}
@@ -148,8 +148,8 @@ function vim.str_utf_pos(str) end
 --- ```
 ---
 --- @param str string
---- @param index number
---- @return number
+--- @param index integer
+--- @return integer
 function vim.str_utf_start(str, index) end
 
 --- Gets the distance (in bytes) from the last byte of the codepoint (character) that {index} points
@@ -168,8 +168,8 @@ function vim.str_utf_start(str, index) end
 --- ```
 ---
 --- @param str string
---- @param index number
---- @return number
+--- @param index integer
+--- @return integer
 function vim.str_utf_end(str, index) end
 
 --- Convert byte index to UTF-32 and UTF-16 indices. If {index} is not
@@ -180,7 +180,7 @@ function vim.str_utf_end(str, index) end
 --- {index} in the middle of a UTF-8 sequence is rounded upwards to the end of
 --- that sequence.
 --- @param str string
---- @param index? number
+--- @param index? integer
 --- @return integer UTF-32 index
 --- @return integer UTF-16 index
 function vim.str_utfindex(str, index) end
@@ -193,15 +193,14 @@ function vim.str_utfindex(str, index) end
 --- can accept, see ":Man 3 iconv".
 ---
 --- @param str string Text to convert
---- @param from number Encoding of {str}
---- @param to number Target encoding
---- @param opts? table<string,any>
---- @return string|nil Converted string if conversion succeeds, `nil` otherwise.
+--- @param from string Encoding of {str}
+--- @param to string Target encoding
+--- @return string? : Converted string if conversion succeeds, `nil` otherwise.
 function vim.iconv(str, from, to, opts) end
 
 --- Schedules {fn} to be invoked soon by the main event-loop. Useful
 --- to avoid |textlock| or other temporary restrictions.
---- @param fn function
+--- @param fn fun()
 function vim.schedule(fn) end
 
 --- Wait for {time} in milliseconds until {callback} returns `true`.
diff --git a/runtime/lua/vim/_meta/diff.lua b/runtime/lua/vim/_meta/diff.lua
index f265139448..617bc87f59 100644
--- a/runtime/lua/vim/_meta/diff.lua
+++ b/runtime/lua/vim/_meta/diff.lua
@@ -1,5 +1,46 @@
 ---@meta
 
+--- Optional parameters:
+--- @class vim.diff.Opts
+--- @inlinedoc
+---
+--- Invoked for each hunk in the diff. Return a negative number
+--- to cancel the callback for any remaining hunks.
+--- Arguments:
+---   - `start_a` (`integer`): Start line of hunk in {a}.
+---   - `count_a` (`integer`): Hunk size in {a}.
+---   - `start_b` (`integer`): Start line of hunk in {b}.
+---   - `count_b` (`integer`): Hunk size in {b}.
+--- @field on_hunk fun(start_a: integer, count_a: integer, start_b: integer, count_b: integer): integer
+---
+--- Form of the returned diff:
+---   - `unified`: String in unified format.
+---   - `indices`: Array of hunk locations.
+--- Note: This option is ignored if `on_hunk` is used.
+--- (default: `'unified'`)
+--- @field result_type 'unified'|'indices'
+---
+--- Run linematch on the resulting hunks from xdiff. When integer, only hunks
+--- upto this size in lines are run through linematch.
+--- Requires `result_type = indices`, ignored otherwise.
+--- @field linematch boolean|integer
+---
+--- Diff algorithm to use. Values:
+---   - `myers`: the default algorithm
+---   - `minimal`: spend extra time to generate the smallest possible diff
+---   - `patience`: patience diff algorithm
+---   - `histogram`: histogram diff algorithm
+--- (default: `'myers'`)
+--- @field algorithm 'myers'|'minimal'|'patience'|'histogram'
+--- @field ctxlen integer Context length
+--- @field interhunkctxlen integer Inter hunk context length
+--- @field ignore_whitespace boolean Ignore whitespace
+--- @field ignore_whitespace_change boolean Ignore whitespace change
+--- @field ignore_whitespace_change_at_eol boolean Ignore whitespace change at end-of-line.
+--- @field ignore_cr_at_eol boolean Ignore carriage return at end-of-line
+--- @field ignore_blank_lines boolean Ignore blank lines
+--- @field indent_heuristic boolean Use the indent heuristic for the internal diff library.
+
 -- luacheck: no unused args
 
 --- Run diff on strings {a} and {b}. Any indices returned by this function,
@@ -24,47 +65,7 @@
 ---
 ---@param a string First string to compare
 ---@param b string Second string to compare
----@param opts table<string,any> Optional parameters:
----     - `on_hunk` (callback):
----       Invoked for each hunk in the diff. Return a negative number
----       to cancel the callback for any remaining hunks.
----       Args:
----       - `start_a` (integer): Start line of hunk in {a}.
----       - `count_a` (integer): Hunk size in {a}.
----       - `start_b` (integer): Start line of hunk in {b}.
----       - `count_b` (integer): Hunk size in {b}.
----     - `result_type` (string): Form of the returned diff:
----       - "unified": (default) String in unified format.
----       - "indices": Array of hunk locations.
----       Note: This option is ignored if `on_hunk` is used.
----     - `linematch` (boolean|integer): Run linematch on the resulting hunks
----       from xdiff. When integer, only hunks upto this size in
----       lines are run through linematch. Requires `result_type = indices`,
----       ignored otherwise.
----     - `algorithm` (string):
----       Diff algorithm to use. Values:
----       - "myers"      the default algorithm
----       - "minimal"    spend extra time to generate the
----                      smallest possible diff
----       - "patience"   patience diff algorithm
----       - "histogram"  histogram diff algorithm
----     - `ctxlen` (integer): Context length
----     - `interhunkctxlen` (integer):
----       Inter hunk context length
----     - `ignore_whitespace` (boolean):
----       Ignore whitespace
----     - `ignore_whitespace_change` (boolean):
----       Ignore whitespace change
----     - `ignore_whitespace_change_at_eol` (boolean)
----       Ignore whitespace change at end-of-line.
----     - `ignore_cr_at_eol` (boolean)
----       Ignore carriage return at end-of-line
----     - `ignore_blank_lines` (boolean)
----       Ignore blank lines
----     - `indent_heuristic` (boolean):
----       Use the indent heuristic for the internal
----       diff library.
----
----@return string|table|nil
+---@param opts vim.diff.Opts
+---@return string|integer[][]?
 ---     See {opts.result_type}. `nil` if {opts.on_hunk} is given.
 function vim.diff(a, b, opts) end
diff --git a/runtime/lua/vim/_meta/re.lua b/runtime/lua/vim/_meta/re.lua
index 14c94c7824..9721e6f8c8 100644
--- a/runtime/lua/vim/_meta/re.lua
+++ b/runtime/lua/vim/_meta/re.lua
@@ -30,8 +30,8 @@ function vim.re.compile(string, defs) end
 --- @param subject string
 --- @param pattern vim.lpeg.Pattern|string
 --- @param init? integer
---- @return integer|nil the index where the occurrence starts, nil if no match
---- @return integer|nil the index where the occurrence ends, nil if no match
+--- @return integer|nil : the index where the occurrence starts, nil if no match
+--- @return integer|nil : the index where the occurrence ends, nil if no match
 function vim.re.find(subject, pattern, init) end
 
 --- Does a global substitution, replacing all occurrences of {pattern} in the given {subject} by
diff --git a/runtime/lua/vim/_meta/spell.lua b/runtime/lua/vim/_meta/spell.lua
index 57f2180895..c636db3b53 100644
--- a/runtime/lua/vim/_meta/spell.lua
+++ b/runtime/lua/vim/_meta/spell.lua
@@ -3,11 +3,11 @@
 -- luacheck: no unused args
 
 --- Check {str} for spelling errors. Similar to the Vimscript function
---- |spellbadword()|.
+--- [spellbadword()].
 ---
 --- Note: The behaviour of this function is dependent on: 'spelllang',
 --- 'spellfile', 'spellcapcheck' and 'spelloptions' which can all be local to
---- the buffer. Consider calling this with |nvim_buf_call()|.
+--- the buffer. Consider calling this with [nvim_buf_call()].
 ---
 --- Example:
 ---
@@ -20,7 +20,7 @@
 --- ```
 ---
 --- @param str string
---- @return {[1]: string, [2]: string, [3]: string}[]
+--- @return {[1]: string, [2]: 'bad'|'rare'|'local'|'caps', [3]: integer}[]
 ---   List of tuples with three items:
 ---     - The badly spelled word.
 ---     - The type of the spelling error:
diff --git a/runtime/lua/vim/treesitter.lua b/runtime/lua/vim/treesitter.lua
index a09619f369..4f4762547a 100644
--- a/runtime/lua/vim/treesitter.lua
+++ b/runtime/lua/vim/treesitter.lua
@@ -257,7 +257,7 @@ end
 ---@param row integer Position row
 ---@param col integer Position column
 ---
----@return table[] List of captures `{ capture = "name", metadata = { ... } }`
+---@return {capture: string, lang: string, metadata: table}[]
 function M.get_captures_at_pos(bufnr, row, col)
   if bufnr == 0 then
     bufnr = api.nvim_get_current_buf()