Merge pull request #24363 from lewis6991/docs/luatypes

docs(lua): move some function docs to lua files

18 files changed, 2090 insertions, 1207 deletions

diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index ec0072e10e..fa109dbc26 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -1189,8 +1189,8 @@ format({options})                                       *vim.lsp.buf.format()*
     server clients.
 
     Parameters: ~
-      • {options}  table|nil Optional table which holds the following optional
-                   fields:
+      • {options}  (table|nil) Optional table which holds the following
+                   optional fields:
                    • formatting_options (table|nil): Can be used to specify
                      FormattingOptions. Some unspecified options will be
                      automatically derived from the current Nvim options. See https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#formattingOptions
@@ -1204,10 +1204,10 @@ format({options})                                       *vim.lsp.buf.format()*
                      Receives a client as argument and must return a boolean.
                      Clients matching the predicate are included. Example:               • >lua
 
-              -- Never request typescript-language-server for formatting
-              vim.lsp.buf.format {
-                filter = function(client) return client.name ~= "tsserver" end
-              }
+               -- Never request typescript-language-server for formatting
+               vim.lsp.buf.format {
+                 filter = function(client) return client.name ~= "tsserver" end
+               }
 <
                    • async boolean|nil If true the method won't block.
                      Defaults to false. Editing the buffer while formatting
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 3f5ab6e00f..fd75fdb2dd 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -565,51 +565,31 @@ A subset of the `vim.*` API is available in threads. This includes:
 - `vim.is_thread()` returns true from a non-main thread.
 
 ------------------------------------------------------------------------------
-VIM.HIGHLIGHT                                                  *lua-highlight*
+VIM.LPEG                                                            *lua-lpeg*
+
+                                                             *vim.lpeg* *vim.re*
+The Lpeg library for parsing expression grammars is being included as
+`vim.lpeg` (https://www.inf.puc-rio.br/~roberto/lpeg/). In addition, its regex-like
+interface is available as `vim.re` (https://www.inf.puc-rio.br/~roberto/lpeg/re.html).
+
+==============================================================================
+VIM.HIGHLIGHT                                                  *vim.highlight*
+
 
-Nvim includes a function for highlighting a selection on yank (see for example
-https://github.com/machakann/vim-highlightedyank). To enable it, add
->vim
+Nvim includes a function for highlighting a selection on yank.
+
+To enable it, add the following to your `init.vim` : >vim
     au TextYankPost * silent! lua vim.highlight.on_yank()
 <
-to your `init.vim`. You can customize the highlight group and the duration of
-the highlight via
->vim
+
+You can customize the highlight group and the duration of the highlight
+via: >vim
     au TextYankPost * silent! lua vim.highlight.on_yank {higroup="IncSearch", timeout=150}
 <
-If you want to exclude visual selections from highlighting on yank, use
->vim
+
+If you want to exclude visual selections from highlighting on yank, use: >vim
     au TextYankPost * silent! lua vim.highlight.on_yank {on_visual=false}
 <
-vim.highlight.on_yank({opts})                        *vim.highlight.on_yank()*
-    Highlights the yanked text. The fields of the optional dict {opts}
-    control the highlight:
-      - {higroup} highlight group for yanked region (default |hl-IncSearch|)
-      - {timeout} time in ms before highlight is cleared (default `150`)
-      - {on_macro} highlight when executing macro (default `false`)
-      - {on_visual} highlight when yanking visual selection (default `true`)
-      - {event} event structure (default |v:event|)
-      - {priority} priority of highlight (default |vim.highlight.priorities|`.user`)
-
-
-vim.highlight.range({bufnr}, {ns}, {hlgroup}, {start}, {finish}, {opts})
-                                                       *vim.highlight.range()*
-
-    Apply highlight group to range of text.
-
-            Parameters: ~
-              • {bufnr}   buffer number
-              • {ns}      namespace for highlights
-              • {hlgroup} highlight group name
-              • {start}   starting position (tuple {line,col})
-              • {finish}  finish position (tuple {line,col})
-              • {opts}    optional parameters:
-                          • `regtype`: type of range (characterwise, linewise,
-                            or blockwise, see |setreg()|), default `'v'`
-                          • `inclusive`: range includes end position,
-                            default `false`
-                          • `priority`: priority of highlight, default
-                            `vim.highlight.user` (see below)
 
 vim.highlight.priorities                            *vim.highlight.priorities*
 
@@ -621,151 +601,209 @@ vim.highlight.priorities                            *vim.highlight.priorities*
         • `user`: `200`, used for user-triggered highlights such as LSP document
           symbols or `on_yank` autocommands
 
-------------------------------------------------------------------------------
-VIM.REGEX                                                          *lua-regex*
+vim.highlight.on_yank({opts})                        *vim.highlight.on_yank()*
+    Highlight the yanked text
+
+    Parameters: ~
+      • {opts}  (table|nil) Optional parameters
+                • higroup highlight group for yanked region (default
+                  "IncSearch")
+                • timeout time in ms before highlight is cleared (default 150)
+                • on_macro highlight when executing macro (default false)
+                • on_visual highlight when yanking visual selection (default
+                  true)
+                • event event structure (default vim.v.event)
+                • priority integer priority (default
+                  |vim.highlight.priorities|`.user`)
+
+                                                       *vim.highlight.range()*
+vim.highlight.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {opts})
+    Apply highlight group to range of text.
+
+    Parameters: ~
+      • {bufnr}    (integer) Buffer number to apply highlighting to
+      • {ns}       (integer) Namespace to add highlight to
+      • {higroup}  (string) Highlight group to use for highlighting
+      • {start}    integer[]|string Start of region as a (line, column) tuple
+                   or string accepted by |getpos()|
+      • {finish}   integer[]|string End of region as a (line, column) tuple or
+                   string accepted by |getpos()|
+      • {opts}     (table|nil) Optional parameters
+                   • regtype type of range (see |setreg()|, default charwise)
+                   • inclusive boolean indicating whether the range is
+                     end-inclusive (default false)
+                   • priority number indicating priority of highlight (default
+                     priorities.user)
+
+
+==============================================================================
+VIM.REGEX                                                          *vim.regex*
+
 
 Vim regexes can be used directly from Lua. Currently they only allow
 matching within a single line.
 
+
 vim.regex({re})                                                  *vim.regex()*
     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|.
 
-Methods on the regex object:
+    Parameters: ~
+      • {re}  (string)
 
-regex:match_str({str})                                     *regex:match_str()*
-    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.
+    Return: ~
+        vim.regex
 
-regex:match_line({bufnr}, {line_idx} [, {start}, {end}])  *regex:match_line()*
+                                                          *regex:match_line()*
+vim.regex:match_line({bufnr}, {line_idx}, {start}, {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}.
 
-------------------------------------------------------------------------------
-VIM.LPEG                                                            *lua-lpeg*
+    Parameters: ~
+      • {bufnr}     (integer)
+      • {line_idx}  (integer)
+      • {start}     (integer|nil)
+      • {end_}      (integer|nil)
 
-                                                             *vim.lpeg* *vim.re*
-The Lpeg library for parsing expression grammars is being included as
-`vim.lpeg` (https://www.inf.puc-rio.br/~roberto/lpeg/). In addition, its regex-like
-interface is available as `vim.re` (https://www.inf.puc-rio.br/~roberto/lpeg/re.html).
+vim.regex:match_str({str})                                 *regex:match_str()*
+    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.
+
+    Parameters: ~
+      • {str}   (string)
 
-------------------------------------------------------------------------------
-VIM.DIFF                                                            *lua-diff*
+
+==============================================================================
+VIM.DIFF                                                            *vim.diff*
 
 vim.diff({a}, {b}, {opts})                                        *vim.diff()*
     Run diff on strings {a} and {b}. Any indices returned by this function,
     either directly or via callback arguments, are 1-based.
 
     Examples: >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}
-        -- }
-<
-    Parameters: ~
-      • {a}      First string to compare
-      • {b}      Second string to compare
-      • {opts}   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: ~
-        See {opts.result_type}. nil if {opts.on_hunk} is given.
 
-------------------------------------------------------------------------------
-VIM.MPACK                                                          *lua-mpack*
+         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}
+         -- }
+<
+
+    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
+                    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.
 
-The *vim.mpack* module provides encoding and decoding of Lua objects to and
-from msgpack-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|.
 
-vim.mpack.encode({obj})                                     *vim.mpack.encode*
-    Encodes (or "packs") Lua object {obj} as msgpack in a Lua string.
+==============================================================================
+VIM.MPACK                                                          *vim.mpack*
+
+
+This module provides encoding and decoding of Lua objects to and from
+msgpack-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|.
 
-vim.mpack.decode({str})                                     *vim.mpack.decode*
+vim.mpack.decode({str})                                   *vim.mpack.decode()*
     Decodes (or "unpacks") the msgpack-encoded {str} to a Lua object.
 
-------------------------------------------------------------------------------
-VIM.JSON                                                            *lua-json*
+    Parameters: ~
+      • {str}  (string)
 
-The *vim.json* module provides encoding and decoding of Lua objects to and
-from JSON-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|.
+vim.mpack.encode({obj})                                   *vim.mpack.encode()*
+    Encodes (or "packs") Lua object {obj} as msgpack in a Lua string.
 
-vim.json.encode({obj})                                       *vim.json.encode*
-    Encodes (or "packs") Lua object {obj} as JSON in a Lua string.
 
-vim.json.decode({str}[, {opts}])                             *vim.json.decode*
+==============================================================================
+VIM.JSON                                                            *vim.json*
+
+
+This module provides encoding and decoding of Lua objects to and from
+JSON-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|.
+
+vim.json.decode({str}, {opts})                             *vim.json.decode()*
     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).
+    • 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: >lua
-    :lua vim.print(vim.json.decode('{"bar":[],"foo":{},"zub":null}'))
-    --> { bar = {}, foo = vim.empty_dict(), zub = vim.NIL }
-<
+
+     :lua vim.print(vim.json.decode('{"bar":[],"foo":{},"zub":null}'))
+     --> { bar = {}, foo = vim.empty_dict(), zub = vim.NIL }
+
+    < 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` .
+
     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`.
+      • {str}   (string)
+      • {opts}  table<string,|nil any>
+
+    Return: ~
+        any
+
+vim.json.encode({obj})                                     *vim.json.encode()*
+    Encodes (or "packs") Lua object {obj} as JSON in a Lua string.
+
+    Parameters: ~
+      • {obj}  any
+
+    Return: ~
+        (string)
 
-------------------------------------------------------------------------------
-VIM.SPELL                                                          *lua-spell*
+
+==============================================================================
+VIM.SPELL                                                          *vim.spell*
 
 vim.spell.check({str})                                     *vim.spell.check()*
     Check {str} for spelling errors. Similar to the Vimscript function
@@ -776,46 +814,85 @@ vim.spell.check({str})                                     *vim.spell.check()*
     the buffer. Consider calling this with |nvim_buf_call()|.
 
     Example: >lua
-        vim.spell.check("the quik brown fox")
-        -- =>
-        -- {
-        --     {'quik', 'bad', 5}
-        -- }
+
+         vim.spell.check("the quik brown fox")
+         -- =>
+         -- {
+         --     {'quik', 'bad', 5}
+         -- }
 <
+
     Parameters: ~
-      • {str}    String to spell check.
+      • {str}  (string)
 
     Return: ~
-      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.
+        `{[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.
+
+
+==============================================================================
+VIM                                                              *vim.builtin*
 
-------------------------------------------------------------------------------
-VIM                                                              *lua-builtin*
 
-vim.api.{func}({...})                                                *vim.api*
+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.in_fast_event()                                      *vim.in_fast_event()*
-    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|).
-
-vim.NIL                                                              *vim.NIL*
+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
+
 vim.empty_dict()                                            *vim.empty_dict()*
     Creates a special empty table (marked with a metatable), which Nvim to an
     empty dictionary when translating Lua values to Vimscript or API types.
@@ -825,215 +902,221 @@ vim.empty_dict()                                            *vim.empty_dict()*
     Note: If numeric keys are present in the table, Nvim ignores the metatable
     marker and converts the dict to a list/array anyway.
 
-vim.rpcnotify({channel}, {method} [, {args}...])             *vim.rpcnotify()*
+vim.iconv({str}, {from}, {to}, {opts})                           *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
+    encoding names are whatever the iconv() library function can accept, see
+    ":Man 3 iconv".
+
+    Parameters: ~
+      • {str}   (string) Text to convert
+      • {from}  (number) Encoding of {str}
+      • {to}    (number) Target encoding
+      • {opts}  table<string,any>|nil
+
+    Return: ~
+        (string|nil) Converted string if conversion succeeds, `nil` otherwise.
+
+vim.in_fast_event()                                      *vim.in_fast_event()*
+    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|).
+
+vim.rpcnotify({channel}, {method}, {args}, {...})            *vim.rpcnotify()*
     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|.
 
-vim.rpcrequest({channel}, {method} [, {args}...])           *vim.rpcrequest()*
+    Parameters: ~
+      • {channel}  (integer)
+      • {method}   (string)
+      • {args}     any[]|nil
+      • {...}      any|nil
+
+vim.rpcrequest({channel}, {method}, {args}, {...})          *vim.rpcrequest()*
     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
 
-vim.stricmp({a}, {b})                                          *vim.stricmp()*
-    Compares strings case-insensitively. Returns 0, 1 or -1 if strings are
-    equal, {a} is greater than {b} or {a} is lesser than {b}, respectively.
+    Parameters: ~
+      • {channel}  (integer)
+      • {method}   (string)
+      • {args}     any[]|nil
+      • {...}      any|nil
 
-vim.str_utfindex({str} [, {index}])                       *vim.str_utfindex()*
-    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.
-    Returns two values: the UTF-32 and UTF-16 indices respectively.
+vim.schedule({callback})                                      *vim.schedule()*
+    Schedules {callback} to be invoked soon by the main event-loop. Useful to
+    avoid |textlock| or other temporary restrictions.
 
-    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.
+    Parameters: ~
+      • {callback}  fun()
 
-vim.str_byteindex({str}, {index} [, {use_utf16}])        *vim.str_byteindex()*
+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
     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.
-
-vim.iconv({str}, {from}, {to}[, {opts}])                        *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 encoding names are whatever the iconv() library function
-        can accept, see ":Man 3 iconv".
+    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.
 
-        Parameters: ~
-          • {str}   (string) Text to convert
-          • {from}  (string) Encoding of {str}
-          • {to}    (string) Target encoding
-
-        Returns: ~
-            Converted string if conversion succeeds, `nil` otherwise.
-
-vim.schedule({callback})                                      *vim.schedule()*
-    Schedules {callback} to be invoked soon by the main event-loop. Useful
-    to avoid |textlock| or other temporary restrictions.
+    Parameters: ~
+      • {str}        (string)
+      • {index}      (number)
+      • {use_utf16}  any|nil
 
-vim.wait({time} [, {callback}, {interval}, {fast_only}])          *vim.wait()*
-    Wait for {time} in milliseconds until {callback} returns `true`.
+vim.str_utfindex({str}, {index})                          *vim.str_utfindex()*
+    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.
 
-    Executes {callback} immediately and at approximately {interval}
-    milliseconds (default 200). Nvim still processes other events during
-    this time.
+    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.
 
     Parameters: ~
-      • {time}      Number of milliseconds to wait
-      • {callback}  Optional callback. Waits until {callback} returns true
-      • {interval}  (Approximate) number of milliseconds to wait between polls
-      • {fast_only} If true, only |api-fast| events will be processed.
-                        If called from while in an |api-fast| event, will
-                        automatically be set to `true`.
+      • {str}    (string)
+      • {index}  (number|nil)
 
-    Returns: ~
-        If {callback} returns `true` during the {time}:
-            `true, nil`
+    Return (multiple): ~
+        (integer) UTF-32 index
+        (integer) UTF-16 index
 
-        If {callback} never returns `true` during the {time}:
-            `false, -1`
+vim.stricmp({a}, {b})                                          *vim.stricmp()*
+    Compares strings case-insensitively.
 
-        If {callback} is interrupted during the {time}:
-            `false, -2`
+    Parameters: ~
+      • {a}  (string)
+      • {b}  (string)
 
-        If {callback} errors, the error is raised.
+    Return: ~
+        0|1|-1 if strings are equal, {a} is greater than {b} or {a} is lesser
+        than {b}, respectively.
 
-        Examples: >lua
+vim.ui_attach({ns}, {options}, {callback})                   *vim.ui_attach()*
+    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.
 
-    ---
-    -- Wait for 100 ms, allowing other events to process
-    vim.wait(100, function() end)
+    {options} should be a dictionary-like table, where `ext_...` options
+    should be set to true to receive events for the respective external
+    element.
 
-    ---
-    -- Wait for 100 ms or until global variable set.
-    vim.wait(100, function() return vim.g.waiting_for_var end)
+    {callback} receives event name plus additional parameters. See
+    |ui-popupmenu| and the sections below for event format for respective
+    events.
 
-    ---
-    -- 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)
+    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