From b8273c9a339626078d49e706d882878090b07d42 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Fri, 26 Apr 2024 14:07:47 +0100 Subject: [PATCH] fix: lua annotations --- runtime/doc/lua.txt | 86 ++++++++++++++++--------------- runtime/doc/treesitter.txt | 3 +- runtime/lua/vim/_defaults.lua | 2 + runtime/lua/vim/_inspector.lua | 6 +-- runtime/lua/vim/_meta/base64.lua | 4 +- runtime/lua/vim/_meta/builtin.lua | 25 +++++---- runtime/lua/vim/_meta/diff.lua | 85 +++++++++++++++--------------- runtime/lua/vim/_meta/re.lua | 4 +- runtime/lua/vim/_meta/spell.lua | 6 +-- runtime/lua/vim/treesitter.lua | 2 +- 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`) 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?`) + • {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 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 ---- @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 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()