docs(lua): move function docs to lua files

7 files changed, 425 insertions, 0 deletions

diff --git a/runtime/lua/vim/_meta/builtin.lua b/runtime/lua/vim/_meta/builtin.lua
new file mode 100644
index 0000000000..384dd4351d
--- /dev/null
+++ b/runtime/lua/vim/_meta/builtin.lua
@@ -0,0 +1,236 @@
+---@meta
+
+---@defgroup lua-builtin
+---
+---@brief <pre>help
+---vim.api.{func}({...})                                                    *vim.api*
+---    Invokes Nvim |API| function {func} with arguments {...}.
+---    Example: call the "nvim_get_current_line()" API function: >lua
+---        print(tostring(vim.api.nvim_get_current_line()))
+---
+---vim.NIL                                                                  *vim.NIL*
+---    Special value representing NIL in |RPC| and |v:null| in Vimscript
+---    conversion, and similar cases. Lua `nil` cannot be used as part of a Lua
+---    table representing a Dictionary or Array, because it is treated as
+---    missing: `{"foo", nil}` is the same as `{"foo"}`.
+---
+---vim.type_idx                                                        *vim.type_idx*
+---    Type index for use in |lua-special-tbl|. Specifying one of the values from
+---    |vim.types| allows typing the empty table (it is unclear whether empty Lua
+---    table represents empty list or empty array) and forcing integral numbers
+---    to be |Float|. See |lua-special-tbl| for more details.
+---
+---vim.val_idx                                                          *vim.val_idx*
+---    Value index for tables representing |Float|s. A table representing
+---    floating-point value 1.0 looks like this: >lua
+---        {
+---          [vim.type_idx] = vim.types.float,
+---          [vim.val_idx] = 1.0,
+---        }
+---<    See also |vim.type_idx| and |lua-special-tbl|.
+---
+---vim.types                                                              *vim.types*
+---    Table with possible values for |vim.type_idx|. Contains two sets of
+---    key-value pairs: first maps possible values for |vim.type_idx| to
+---    human-readable strings, second maps human-readable type names to values
+---    for |vim.type_idx|. Currently contains pairs for `float`, `array` and
+---        `dictionary` types.
+---
+---    Note: One must expect that values corresponding to `vim.types.float`,
+---    `vim.types.array` and `vim.types.dictionary` fall under only two following
+---    assumptions:
+---    1. Value may serve both as a key and as a value in a table. Given the
+---       properties of Lua tables this basically means “value is not `nil`”.
+---    2. For each value in `vim.types` table `vim.types[vim.types[value]]` is the
+---       same as `value`.
+---    No other restrictions are put on types, and it is not guaranteed that
+---    values corresponding to `vim.types.float`, `vim.types.array` and
+---    `vim.types.dictionary` will not change or that `vim.types` table will only
+---    contain values for these three types.
+---
+---                                                   *log_levels* *vim.log.levels*
+---Log levels are one of the values defined in `vim.log.levels`:
+---
+---    vim.log.levels.DEBUG
+---    vim.log.levels.ERROR
+---    vim.log.levels.INFO
+---    vim.log.levels.TRACE
+---    vim.log.levels.WARN
+---    vim.log.levels.OFF
+---
+---</pre>
+
+--- Returns true if the code is executing as part of a "fast" event handler,
+--- where most of the API is disabled. These are low-level events (e.g.
+--- |lua-loop-callbacks|) which can be invoked whenever Nvim polls for input.
+--- When this is `false` most API functions are callable (but may be subject
+--- to other restrictions such as |textlock|).
+function vim.in_fast_event() end
+
+--- Creates a special empty table (marked with a metatable), which Nvim to an
+--- empty dictionary when translating Lua values to Vimscript or API types.
+--- Nvim by default converts an empty table `{}` without this metatable to an
+--- list/array.
+---
+--- Note: If numeric keys are present in the table, Nvim ignores the metatable
+--- marker and converts the dict to a list/array anyway.
+function vim.empty_dict() end
+
+--- Sends {event} to {channel} via |RPC| and returns immediately. If {channel}
+--- is 0, the event is broadcast to all channels.
+---
+--- This function also works in a fast callback |lua-loop-callbacks|.
+--- @param channel integer
+--- @param method string
+--- @param args? any[]
+--- @param ...? any
+function vim.rpcnotify(channel, method, args, ...) end
+
+--- Sends a request to {channel} to invoke {method} via |RPC| and blocks until
+--- a response is received.
+---
+--- Note: NIL values as part of the return value is represented as |vim.NIL|
+--- special value
+--- @param channel integer
+--- @param method string
+--- @param args? any[]
+--- @param ...? any
+function vim.rpcrequest(channel, method, args, ...) end
+
+--- Compares strings case-insensitively.
+--- @param a string
+--- @param b string
+--- @return 0|1|-1
+--- if strings are
+--- equal, {a} is greater than {b} or {a} is lesser than {b}, respectively.
+function vim.stricmp(a, b) end
+
+--- Convert UTF-32 or UTF-16 {index} to byte index. If {use_utf16} is not
+--- supplied, it defaults to false (use UTF-32). Returns the byte index.
+---
+--- Invalid UTF-8 and NUL is treated like by |vim.str_byteindex()|.
+--- 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
+function vim.str_byteindex(str, index, use_utf16) end
+
+--- Convert byte index to UTF-32 and UTF-16 indices. If {index} is not
+--- supplied, the length of the string is used. All indices are zero-based.
+---
+--- Embedded NUL bytes are treated as terminating the string. Invalid UTF-8
+--- bytes, and embedded surrogates are counted as one code point each. An
+--- {index} in the middle of a UTF-8 sequence is rounded upwards to the end of
+--- that sequence.
+--- @param str string
+--- @param index? number
+--- @return integer UTF-32 index
+--- @return integer UTF-16 index
+function vim.str_utfindex(str, index) end
+
+--- 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 encoding names are whatever the iconv() library function
+--- 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.
+function vim.iconv(str, from, to, opts) end
+
+--- Schedules {callback} to be invoked soon by the main event-loop. Useful
+--- to avoid |textlock| or other temporary restrictions.
+--- @param callback fun()
+function vim.schedule(callback) end
+
+--- Wait for {time} in milliseconds until {callback} returns `true`.
+---
+--- Executes {callback} immediately and at approximately {interval}
+--- milliseconds (default 200). Nvim still processes other events during
+--- this time.
+---
+--- Examples:
+--- <pre>lua
+---
+--- ---
+--- -- Wait for 100 ms, allowing other events to process
+--- vim.wait(100, function() end)
+---
+--- ---
+--- -- Wait for 100 ms or until global variable set.
+--- vim.wait(100, function() return vim.g.waiting_for_var end)
+---
+--- ---
+--- -- Wait for 1 second or until global variable set, checking every ~500 ms
+--- vim.wait(1000, function() return vim.g.waiting_for_var end, 500)
+---
+--- ---
+--- -- Schedule a function to set a value in 100ms
+--- vim.defer_fn(function() vim.g.timer_result = true end, 100)
+---
+--- -- Would wait ten seconds if results blocked. Actually only waits  100 ms
+--- if vim.wait(10000, function() return vim.g.timer_result end) then
+---   print('Only waiting a little bit of time!')
+--- end
+--- </pre>
+---
+--- @param time integer Number of milliseconds to wait
+--- @param callback? fun(): boolean Optional callback. Waits until {callback} returns true
+--- @param interval? integer (Approximate) number of milliseconds to wait between polls
+--- @param fast_only? boolean If true, only |api-fast| events will be processed.
+---                           If called from while in an |api-fast| event, will
+---                           automatically be set to `true`.
+--- @return boolean, nil|-1|-2
+---     - If {callback} returns `true` during the {time}: `true, nil`
+---     - If {callback} never returns `true` during the {time}: `false, -1`
+---     - If {callback} is interrupted during the {time}: `false, -2`
+---     - If {callback} errors, the error is raised.
+function vim.wait(time, callback, interval, fast_only) end
+
+--- Attach to ui events, similar to |nvim_ui_attach()| but receive events
+--- as Lua callback. Can be used to implement screen elements like
+--- popupmenu or message handling in Lua.
+---
+--- {options} should be a dictionary-like table, where `ext_...` options should
+--- be set to true to receive events for the respective external element.
+---
+--- {callback} receives event name plus additional parameters. See |ui-popupmenu|
+--- and the sections below for event format for respective events.
+---
+--- WARNING: This api is considered experimental.  Usability will vary for
+--- different screen elements. In particular `ext_messages` behavior is subject
+--- to further changes and usability improvements.  This is expected to be
+--- used to handle messages when setting 'cmdheight' to zero (which is
+--- likewise experimental).
+---
+--- Example (stub for a |ui-popupmenu| implementation):
+--- <pre>lua
+---
+---   ns = vim.api.nvim_create_namespace('my_fancy_pum')
+---
+---   vim.ui_attach(ns, {ext_popupmenu=true}, function(event, ...)
+---     if event == "popupmenu_show" then
+---       local items, selected, row, col, grid = ...
+---       print("display pum ", #items)
+---     elseif event == "popupmenu_select" then
+---       local selected = ...
+---       print("selected", selected)
+---     elseif event == "popupmenu_hide" then
+---       print("FIN")
+---     end
+---   end)
+--- </pre>
+--- @param ns integer
+--- @param options table<string, any>
+--- @param callback fun()
+function vim.ui_attach(ns, options, callback) end
+
+--- Detach a callback previously attached with |vim.ui_attach()| for the
+--- given namespace {ns}.
+--- @param ns integer
+function vim.ui_detach(ns) end
diff --git a/runtime/lua/vim/_meta/diff.lua b/runtime/lua/vim/_meta/diff.lua
new file mode 100644
index 0000000000..8e8aaf8b64
--- /dev/null
+++ b/runtime/lua/vim/_meta/diff.lua
@@ -0,0 +1,67 @@
+---@meta
+
+--- Run diff on strings {a} and {b}. Any indices returned by this function,
+--- either directly or via callback arguments, are 1-based.
+---
+--- Examples:
+--- <pre>lua
+---     vim.diff('a\\n', 'b\\nc\\n')
+---     -- =>
+---     -- @@ -1 +1,2 @@
+---     -- -a
+---     -- +b
+---     -- +c
+---
+---     vim.diff('a\\n', 'b\\nc\\n', {result_type = 'indices'})
+---     -- =>
+---     -- {
+---     --   {1, 1, 1, 2}
+---     -- }
+--- </pre>
+---
+--- @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
+---     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/json.lua b/runtime/lua/vim/_meta/json.lua
new file mode 100644
index 0000000000..15e81d5004
--- /dev/null
+++ b/runtime/lua/vim/_meta/json.lua
@@ -0,0 +1,35 @@
+--- @meta
+
+--- @defgroup lua-json
+---
+--- @brief The \*vim.json\* module provides encoding and decoding of Lua objects to and
+--- from JSON-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|.
+
+--- Decodes (or "unpacks") the JSON-encoded {str} to a Lua object.
+---
+--- - Decodes JSON "null" as |vim.NIL| (controllable by {opts}, see below).
+--- - Decodes empty object as |vim.empty_dict()|.
+--- - Decodes empty array as `{}` (empty Lua table).
+---
+--- Example:
+--- <pre>lua
+--- :lua vim.print(vim.json.decode('{"bar":[],"foo":{},"zub":null}'))
+--- --> { bar = {}, foo = vim.empty_dict(), zub = vim.NIL }
+--- </pre>
+--- Parameters: ~
+---   • {str}    Stringified JSON data.
+---   • {opts}   Options map keys:
+---              • luanil: { object: bool, array: bool }
+---                • `luanil.object=true` converts `null` in JSON objects to
+---                  Lua `nil` instead of `vim.NIL`.
+---                • `luanil.array=true` converts `null` in JSON arrays to Lua
+---                  `nil` instead of `vim.NIL`.
+--- @param str string
+--- @param opts? table<string, any>
+--- @return any
+function vim.json.decode(str, opts) end
+
+--- Encodes (or "packs") Lua object {obj} as JSON in a Lua string.
+--- @param obj any
+--- @return string
+function vim.json.encode(obj) end
diff --git a/runtime/lua/vim/_meta/misc.lua b/runtime/lua/vim/_meta/misc.lua
new file mode 100644
index 0000000000..954e8b4675
--- /dev/null
+++ b/runtime/lua/vim/_meta/misc.lua
@@ -0,0 +1,11 @@
+---@meta
+
+--- Invokes |vim-function| or |user-function| {func} with arguments {...}.
+--- See also |vim.fn|.
+--- Equivalent to:
+--- <pre>lua
+---     vim.fn[func]({...})
+--- </pre>
+--- @param func fun()
+--- @param ... any
+function vim.call(func, ...) end
diff --git a/runtime/lua/vim/_meta/mpack.lua b/runtime/lua/vim/_meta/mpack.lua
new file mode 100644
index 0000000000..2764177e5c
--- /dev/null
+++ b/runtime/lua/vim/_meta/mpack.lua
@@ -0,0 +1,13 @@
+--- @meta
+
+--- @defgroup lua-mpack
+---
+--- @brief The \*vim.mpack\* module provides encoding and decoding of Lua objects to and
+--- from msgpack-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|.
+
+--- Decodes (or "unpacks") the msgpack-encoded {str} to a Lua object.
+--- @param str string
+function vim.mpack.decode(str) end
+
+--- Encodes (or "packs") Lua object {obj} as msgpack in a Lua string.
+function vim.mpack.encode(obj) end
diff --git a/runtime/lua/vim/_meta/regex.lua b/runtime/lua/vim/_meta/regex.lua
new file mode 100644
index 0000000000..afa78772da
--- /dev/null
+++ b/runtime/lua/vim/_meta/regex.lua
@@ -0,0 +1,34 @@
+--- @meta
+
+--- @defgroup lua-regex
+---
+--- @brief Vim regexes can be used directly from Lua. Currently they only allow
+--- matching within a single line.
+
+--- Parse the Vim regex {re} and return a regex object. Regexes are "magic"
+--- and case-sensitive by default, regardless of 'magic' and 'ignorecase'.
+--- They can be controlled with flags, see |/magic| and |/ignorecase|.
+--- @param re string
+--- @return vim.regex
+function vim.regex(re) end
+
+--- @class vim.regex
+local regex = {}
+
+--- Match the string against the regex. If the string should match the regex
+--- precisely, surround the regex with `^` and `$`. If the was a match, the
+--- byte indices for the beginning and end of the match is returned. When
+--- there is no match, `nil` is returned. As any integer is truth-y,
+--- `regex:match()` can be directly used as a condition in an if-statement.
+--- @param str string
+function regex:match_str(str) end
+
+--- Match line {line_idx} (zero-based) in buffer {bufnr}. If {start} and {end}
+--- are supplied, match only this byte index range. Otherwise see
+--- |regex:match_str()|. If {start} is used, then the returned byte indices
+--- will be relative {start}.
+--- @param bufnr integer
+--- @param line_idx integer
+--- @param start? integer
+--- @param end_? integer
+function regex:match_line(bufnr, line_idx, start, end_) end
diff --git a/runtime/lua/vim/_meta/spell.lua b/runtime/lua/vim/_meta/spell.lua
new file mode 100644
index 0000000000..926c8a686d
--- /dev/null
+++ b/runtime/lua/vim/_meta/spell.lua
@@ -0,0 +1,29 @@
+--- @meta
+
+--- Check {str} for spelling errors. Similar to the Vimscript function
+--- |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()|.
+---
+--- Example:
+--- <pre>lua
+---     vim.spell.check("the quik brown fox")
+---     -- =>
+---     -- {
+---     --     {'quik', 'bad', 5}
+---     -- }
+--- </pre>
+---
+--- @param str string
+--- @return {[1]: string, [2]: string, [3]: string}[]
+---   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 start with Capital
+---     - The position in {str} where the word begins.
+function vim.spell.check(str) end