docs(lua): move function docs to lua files

11 files changed, 1404 insertions, 464 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 81449bc454..d53b66a865 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.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                                                  *lua-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,41 +601,83 @@ vim.highlight.priorities                            *vim.highlight.priorities*
         • `user`: `200`, used for user-triggered highlights such as LSP document
           symbols or `on_yank` autocommands
 
-------------------------------------------------------------------------------
+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                                                          *lua-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({a}, {b}, {opts})                                        *vim.diff()*
@@ -663,108 +685,127 @@ vim.diff({a}, {b}, {opts})                                        *vim.diff()*
     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.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.
+
+
+==============================================================================
 VIM.MPACK                                                          *lua-mpack*
 
-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.
+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.decode({str})                                     *vim.mpack.decode*
+
+vim.mpack.decode({str})                                   *vim.mpack.decode()*
     Decodes (or "unpacks") the msgpack-encoded {str} to a Lua object.
 
-------------------------------------------------------------------------------
+    Parameters: ~
+      • {str}  (string)
+
+vim.mpack.encode({obj})                                   *vim.mpack.encode()*
+    Encodes (or "packs") Lua object {obj} as msgpack in a Lua string.
+
+
+==============================================================================
 VIM.JSON                                                            *lua-json*
 
+
 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.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.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.check({str})                                     *vim.spell.check()*
@@ -776,46 +817,86 @@ 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                                                              *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 +906,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,|nil any>
+
+    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".
-
-        Parameters: ~
-          • {str}   (string) Text to convert
-          • {from}  (string) Encoding of {str}
-          • {to}    (string) Target encoding
+    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.
 
-        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
+    likewise experimental).
 
-    ---
-    -- Schedule a function to set a value in 100ms
-    vim.defer_fn(function() vim.g.timer_result = true end, 100)
+    Example (stub for a |ui-popupmenu| implementation): >lua
 
-    -- 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
+       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)
 <
 
-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.
+    Parameters: ~
+      • {ns}        (integer)
+      • {options}   table<string, any>
+      • {callback}  fun()
 
-    {options} should be a dictionary-like table, where `ext_...` options should
-    be set to true to receive events for the respective external element.
+vim.ui_detach({ns})                                          *vim.ui_detach()*
+    Detach a callback previously attached with |vim.ui_attach()| for the given
+    namespace {ns}.
 
-    {callback} receives event name plus additional parameters. See |ui-popupmenu|
-    and the sections below for event format for respective events.
+    Parameters: ~
+      • {ns}  (integer)
 
-    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).
+vim.wait({time}, {callback}, {interval}, {fast_only})             *vim.wait()*
+    Wait for {time} in milliseconds until {callback} returns `true`.
 
-    Example (stub for a |ui-popupmenu| implementation): >lua
+    Executes {callback} immediately and at approximately {interval}
+    milliseconds (default 200). Nvim still processes other events during this
+    time.
 
-      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)
+    Examples: >lua
 
-vim.ui_detach({ns})                                           *vim.ui_detach()*
-    Detach a callback previously attached with |vim.ui_attach()| for the
-    given namespace {ns}.
+     ---
+     -- Wait for 100 ms, allowing other events to process
+     vim.wait(100, function() end)
 
-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.
+     ---
+     -- Wait for 100 ms or until global variable set.
+     vim.wait(100, function() return vim.g.waiting_for_var end)
 
-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|.
+     ---
+     -- 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)
 
-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.
+     ---
+     -- Schedule a function to set a value in 100ms
+     vim.defer_fn(function() vim.g.timer_result = true end, 100)
 
-    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.
+     -- 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
+<
 
-                                                   *log_levels* *vim.log.levels*
-Log levels are one of the values defined in `vim.log.levels`:
+    Parameters: ~
+      • {time}       (integer) Number of milliseconds to wait
+      • {callback}   fun():|nil boolean Optional callback. Waits until
+                     {callback} returns true
+      • {interval}   (integer|nil) (Approximate) number of milliseconds to
+                     wait between polls
+      • {fast_only}  (boolean|nil) If true, only |api-fast| events will be
+                     processed. If called from while in an |api-fast| event,
+                     will automatically be set to `true`.
 
-    vim.log.levels.DEBUG
-    vim.log.levels.ERROR
-    vim.log.levels.INFO
-    vim.log.levels.TRACE
-    vim.log.levels.WARN
-    vim.log.levels.OFF
+    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.
 
-------------------------------------------------------------------------------
+
+==============================================================================
 LUA-VIMSCRIPT BRIDGE                                           *lua-vimscript*
 
+
 Nvim Lua provides an interface or "bridge" to Vimscript variables and
 functions, and editor commands and options.
 
 Objects passed over this bridge are COPIED (marshalled): there are no
-"references". |lua-guide-variables| For example, using `vim.fn.remove()` on
-a Lua list copies the list object to Vimscript and does NOT modify the Lua
-list: >lua
-
+"references". |lua-guide-variables| For example, using `vim.fn.remove()`
+on a Lua list copies the list object to Vimscript and does NOT modify the
+Lua list: >lua
     local list = { 1, 2, 3 }
     vim.fn.remove(list, 0)
     vim.print(list)  --> "{ 1, 2, 3 }"
-
+<
 
 vim.call({func}, {...})                                           *vim.call()*
     Invokes |vim-function| or |user-function| {func} with arguments {...}.
     See also |vim.fn|.
     Equivalent to: >lua
         vim.fn[func]({...})
-
+<
 vim.cmd({command})
     See |vim.cmd()|.
 
@@ -1115,7 +1202,7 @@ vim.env                                                              *vim.env*
         print(vim.env.TERM)
 <
 
-                                                                 *lua-options*
+` `                                                                *lua-options*
                                                              *lua-vim-options*
                                                                  *lua-vim-set*
                                                             *lua-vim-setlocal*
@@ -1149,6 +1236,7 @@ vim.o                                                                  *vim.o*
         print(vim.o.columns)
         print(vim.o.foo)     -- error: invalid key
 <
+
 vim.go                                                                *vim.go*
     Get or set global |options|. Like `:setglobal`. Invalid key is
     an error.
@@ -1162,6 +1250,7 @@ vim.go                                                                *vim.go*
         print(vim.go.columns)
         print(vim.go.bar)     -- error: invalid key
 <
+
 vim.bo[{bufnr}]                                                                *vim.bo*
     Get or set buffer-scoped |options| for the buffer with number {bufnr}.
     Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current
@@ -1174,7 +1263,7 @@ vim.bo[{bufnr}]                                                                *
         vim.bo[bufnr].buflisted = true    -- same as vim.bo.buflisted = true
         print(vim.bo.comments)
         print(vim.bo.baz)                 -- error: invalid key
-<
+
 vim.wo[{winid}][{bufnr}]                                                       *vim.wo*
     Get or set window-scoped |options| for the window with handle {winid} and
     buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like
@@ -1192,13 +1281,10 @@ vim.wo[{winid}][{bufnr}]                                                       *
         vim.wo[winid][0].spell = false -- like ':setlocal nospell'
 <
 
-
-
-                                                                        *vim.opt_local*
+` `                                                                       *vim.opt_local*
                                                                        *vim.opt_global*
                                                                               *vim.opt*
 
-
 A special interface |vim.opt| exists for conveniently interacting with list-
 and map-style option from Lua: It allows accessing them as Lua tables and
 offers object-oriented method for adding and removing entries.
@@ -1258,11 +1344,18 @@ In any of the above examples, to replicate the behavior |:setlocal|, use
 `vim.opt_local`. Additionally, to replicate the behavior of |:setglobal|, use
 `vim.opt_global`.
 
+Option:append({value})                                      *vim.opt:append()*
+    Append a value to string-style options. See |:set+=|
 
+    These are equivalent: >lua
+        vim.opt.formatoptions:append('j')
+        vim.opt.formatoptions = vim.opt.formatoptions + 'j'
+<
 
-                                                               *vim.opt:get()*
-Option:get()
+    Parameters: ~
+      • {value}  (string) Value to append
 
+Option:get()                                                   *vim.opt:get()*
     Returns a Lua-representation of the option. Boolean, number and string
     values will be returned in exactly the same fashion.
 
@@ -1279,6 +1372,7 @@ Option:get()
         -- Will ignore: *.pyc
         -- Will ignore: *.o
 <
+
     For values that are comma-separated maps, a table will be returned with
     the names as keys and the values as entries: >lua
         vim.cmd [[set listchars=space:_,tab:>~]]
@@ -1290,6 +1384,7 @@ Option:get()
             print(char, "=>", representation)
         end
 <
+
     For values that are lists of flags, a set will be returned with the flags
     as keys and `true` as entries. >lua
         vim.cmd [[set formatoptions=njtcroql]]
@@ -1302,27 +1397,22 @@ Option:get()
             print("J is enabled!")
         end
 <
-                                                            *vim.opt:append()*
-Option:append(value)
 
-    Append a value to string-style options. See |:set+=|
-
-    These are equivalent: >lua
-        vim.opt.formatoptions:append('j')
-        vim.opt.formatoptions = vim.opt.formatoptions + 'j'
-<
-                                                           *vim.opt:prepend()*
-Option:prepend(value)
+    Return: ~
+        string|integer|boolean|nil value of option
 
+Option:prepend({value})                                    *vim.opt:prepend()*
     Prepend a value to string-style options. See |:set^=|
 
     These are equivalent: >lua
         vim.opt.wildignore:prepend('*.o')
         vim.opt.wildignore = vim.opt.wildignore ^ '*.o'
 <
-                                                            *vim.opt:remove()*
-Option:remove(value)
 
+    Parameters: ~
+      • {value}  (string) Value to prepend
+
+Option:remove({value})                                      *vim.opt:remove()*
     Remove a value from string-style options. See |:set-=|
 
     These are equivalent: >lua
@@ -1330,10 +1420,14 @@ Option:remove(value)
         vim.opt.wildignore = vim.opt.wildignore - '*.pyc'
 <
 
+    Parameters: ~
+      • {value}  (string) Value to remove
+
+
 ==============================================================================
 Lua module: vim                                                      *lua-vim*
 
-cmd({command})                                                     *vim.cmd()*
+vim.cmd({command})                                                 *vim.cmd()*
     Execute Vim script commands.
 
     Note that `vim.cmd` can be indexed with a command name to return a
@@ -1379,10 +1473,10 @@ cmd({command})                                                     *vim.cmd()*
       • |ex-cmd-index|
 
                                              *vim.connection_failure_errmsg()*
-connection_failure_errmsg({consequence})
+vim.connection_failure_errmsg({consequence})
     TODO: Documentation
 
-defer_fn({fn}, {timeout})                                     *vim.defer_fn()*
+vim.defer_fn({fn}, {timeout})                                 *vim.defer_fn()*
     Defers calling {fn} until {timeout} ms passes.
 
     Use to do a one-shot timer that calls {fn} Note: The {fn} is
@@ -1397,7 +1491,7 @@ defer_fn({fn}, {timeout})                                     *vim.defer_fn()*
         (table) timer luv timer object
 
                                                              *vim.deprecate()*
-deprecate({name}, {alternative}, {version}, {plugin}, {backtrace})
+vim.deprecate({name}, {alternative}, {version}, {plugin}, {backtrace})
     Shows a deprecation message to the user.
 
     Parameters: ~
@@ -1411,7 +1505,7 @@ deprecate({name}, {alternative}, {version}, {plugin}, {backtrace})
     Return: ~
         (string|nil) # Deprecated message, or nil if no message was shown.
 
-inspect({object}, {options})                                   *vim.inspect()*
+vim.inspect({object}, {options})                               *vim.inspect()*
     Gets a human-readable representation of the given object.
 
     See also: ~
@@ -1419,7 +1513,7 @@ inspect({object}, {options})                                   *vim.inspect()*
       • https://github.com/kikito/inspect.lua
       • https://github.com/mpeterv/vinspect
 
-keycode({str})                                                 *vim.keycode()*
+vim.keycode({str})                                             *vim.keycode()*
     Translate keycodes.
 
     Example: >lua
@@ -1437,13 +1531,13 @@ keycode({str})                                                 *vim.keycode()*
     See also: ~
       • |nvim_replace_termcodes()|
 
-lua_omnifunc({find_start}, {_})                           *vim.lua_omnifunc()*
+vim.lua_omnifunc({find_start}, {_})                       *vim.lua_omnifunc()*
     Omnifunc for completing Lua values from the runtime Lua interpreter,
     similar to the builtin completion for the `:lua` command.
 
     Activate using `set omnifunc=v:lua.vim.lua_omnifunc` in a Lua buffer.
 
-notify({msg}, {level}, {opts})                                  *vim.notify()*
+vim.notify({msg}, {level}, {opts})                              *vim.notify()*
     Display a notification to the user.
 
     This function can be overridden by plugins to display notifications using
@@ -1455,7 +1549,7 @@ notify({msg}, {level}, {opts})                                  *vim.notify()*
       • {level}  (integer|nil) One of the values from |vim.log.levels|.
       • {opts}   (table|nil) Optional parameters. Unused by default.
 
-notify_once({msg}, {level}, {opts})                        *vim.notify_once()*
+vim.notify_once({msg}, {level}, {opts})                    *vim.notify_once()*
     Display a notification only one time.
 
     Like |vim.notify()|, but subsequent calls with the same message will not
@@ -1469,7 +1563,7 @@ notify_once({msg}, {level}, {opts})                        *vim.notify_once()*
     Return: ~
         (boolean) true if message was displayed, else false
 
-on_key({fn}, {ns_id})                                           *vim.on_key()*
+vim.on_key({fn}, {ns_id})                                       *vim.on_key()*
     Adds Lua function {fn} with namespace id {ns_id} as a listener to every,
     yes every, input key.
 
@@ -1492,7 +1586,7 @@ on_key({fn}, {ns_id})                                           *vim.on_key()*
         (integer) Namespace id associated with {fn}. Or count of all callbacks
         if on_key() is called without arguments.
 
-paste({lines}, {phase})                                          *vim.paste()*
+vim.paste({lines}, {phase})                                      *vim.paste()*
     Paste handler, invoked by |nvim_paste()| when a conforming UI (such as the
     |TUI|) pastes text into the editor.
 
@@ -1524,7 +1618,7 @@ paste({lines}, {phase})                                          *vim.paste()*
     See also: ~
       • |paste| @alias paste_phase -1 | 1 | 2 | 3
 
-print({...})                                                     *vim.print()*
+vim.print({...})                                                 *vim.print()*
     "Pretty prints" the given arguments and returns them unmodified.
 
     Example: >lua
@@ -1539,7 +1633,8 @@ print({...})                                                     *vim.print()*
       • |vim.inspect()|
       • |:=|
 
-region({bufnr}, {pos1}, {pos2}, {regtype}, {inclusive})         *vim.region()*
+                                                                *vim.region()*
+vim.region({bufnr}, {pos1}, {pos2}, {regtype}, {inclusive})
     Gets a dict of line segment ("chunk") positions for the region from `pos1`
     to `pos2`.
 
@@ -1562,7 +1657,7 @@ region({bufnr}, {pos1}, {pos2}, {regtype}, {inclusive})         *vim.region()*
         `endcol` is exclusive, and whole lines are returned as
         `{startcol,endcol} = {0,-1}`.
 
-schedule_wrap({cb})                                      *vim.schedule_wrap()*
+vim.schedule_wrap({cb})                                  *vim.schedule_wrap()*
     Defers callback `cb` until the Nvim API is safe to call.
 
     Parameters: ~
@@ -1576,7 +1671,7 @@ schedule_wrap({cb})                                      *vim.schedule_wrap()*
       • |vim.schedule()|
       • |vim.in_fast_event()|
 
-system({cmd}, {opts}, {on_exit})                                *vim.system()*
+vim.system({cmd}, {opts}, {on_exit})                            *vim.system()*
     Run a system command
 
     Examples: >lua
@@ -1649,9 +1744,9 @@ system({cmd}, {opts}, {on_exit})                                *vim.system()*
 
 
 ==============================================================================
-Lua module: inspector                                          *lua-inspector*
+Lua module: vim.inspector                                      *lua-inspector*
 
-inspect_pos({bufnr}, {row}, {col}, {filter})               *vim.inspect_pos()*
+vim.inspect_pos({bufnr}, {row}, {col}, {filter})           *vim.inspect_pos()*
     Get all the items at a given buffer position.
 
     Can also be pretty-printed with `:Inspect!`.                   *:Inspect!*
@@ -1684,7 +1779,7 @@ inspect_pos({bufnr}, {row}, {col}, {filter})               *vim.inspect_pos()*
         • row: the row used to get the items
         • col: the col used to get the items
 
-show_pos({bufnr}, {row}, {col}, {filter})                     *vim.show_pos()*
+vim.show_pos({bufnr}, {row}, {col}, {filter})                 *vim.show_pos()*
     Show all the items at a given buffer position.
 
     Can also be shown with `:Inspect`.                              *:Inspect*
@@ -1700,7 +1795,7 @@ show_pos({bufnr}, {row}, {col}, {filter})                     *vim.show_pos()*
 
 
 
-deep_equal({a}, {b})                                        *vim.deep_equal()*
+vim.deep_equal({a}, {b})                                    *vim.deep_equal()*
     Deep compare values for equality
 
     Tables are compared recursively unless they both provide the `eq` metamethod. All other types are compared using the equality `==` operator.
@@ -1712,7 +1807,7 @@ deep_equal({a}, {b})                                        *vim.deep_equal()*
     Return: ~
         (boolean) `true` if values are equals, else `false`
 
-deepcopy({orig})                                              *vim.deepcopy()*
+vim.deepcopy({orig})                                          *vim.deepcopy()*
     Returns a deep copy of the given object. Non-table objects are copied as
     in a typical Lua assignment, whereas table objects are copied recursively.
     Functions are naively copied, so functions in the copied table point to
@@ -1725,7 +1820,7 @@ deepcopy({orig})                                              *vim.deepcopy()*
     Return: ~
         (table) Table of copied keys and (nested) values.
 
-defaulttable({create})                                    *vim.defaulttable()*
+vim.defaulttable({create})                                *vim.defaulttable()*
     Creates a table whose members are automatically created when accessed, if
     they don't already exist.
 
@@ -1748,7 +1843,7 @@ defaulttable({create})                                    *vim.defaulttable()*
     Return: ~
         (table) Empty table with metamethod
 
-endswith({s}, {suffix})                                       *vim.endswith()*
+vim.endswith({s}, {suffix})                                   *vim.endswith()*
     Tests if `s` ends with `suffix`.
 
     Parameters: ~
@@ -1758,7 +1853,7 @@ endswith({s}, {suffix})                                       *vim.endswith()*
     Return: ~
         (boolean) `true` if `suffix` is a suffix of `s`
 
-gsplit({s}, {sep}, {opts})                                      *vim.gsplit()*
+vim.gsplit({s}, {sep}, {opts})                                  *vim.gsplit()*
     Splits a string at each instance of a separator.
 
     Example: >lua
@@ -1794,7 +1889,7 @@ gsplit({s}, {sep}, {opts})                                      *vim.gsplit()*
       • https://www.lua.org/pil/20.2.html
       • http://lua-users.org/wiki/StringLibraryTutorial
 
-is_callable({f})                                           *vim.is_callable()*
+vim.is_callable({f})                                       *vim.is_callable()*
     Returns true if object `f` can be called as a function.
 
     Parameters: ~
@@ -1803,7 +1898,7 @@ is_callable({f})                                           *vim.is_callable()*
     Return: ~
         (boolean) `true` if `f` is callable, else `false`
 
-list_contains({t}, {value})                              *vim.list_contains()*
+vim.list_contains({t}, {value})                          *vim.list_contains()*
     Checks if a list-like table (integer keys without gaps) contains `value`.
 
     Parameters: ~
@@ -1816,7 +1911,7 @@ list_contains({t}, {value})                              *vim.list_contains()*
     See also: ~
       • |vim.tbl_contains()| for checking values in general tables
 
-list_extend({dst}, {src}, {start}, {finish})               *vim.list_extend()*
+vim.list_extend({dst}, {src}, {start}, {finish})           *vim.list_extend()*
     Extends a list-like table with the values of another list-like table.
 
     NOTE: This mutates dst!
@@ -1833,7 +1928,7 @@ list_extend({dst}, {src}, {start}, {finish})               *vim.list_extend()*
     See also: ~
       • |vim.tbl_extend()|
 
-list_slice({list}, {start}, {finish})                       *vim.list_slice()*
+vim.list_slice({list}, {start}, {finish})                   *vim.list_slice()*
     Creates a copy of a table containing only elements from start to end
     (inclusive)
 
@@ -1845,7 +1940,7 @@ list_slice({list}, {start}, {finish})                       *vim.list_slice()*
     Return: ~
         (list) Copy of table sliced from start to finish (inclusive)
 
-pesc({s})                                                         *vim.pesc()*
+vim.pesc({s})                                                     *vim.pesc()*
     Escapes magic chars in |lua-patterns|.
 
     Parameters: ~
@@ -1857,7 +1952,7 @@ pesc({s})                                                         *vim.pesc()*
     See also: ~
       • https://github.com/rxi/lume
 
-ringbuf({size})                                                *vim.ringbuf()*
+vim.ringbuf({size})                                            *vim.ringbuf()*
     Create a ring buffer limited to a maximal number of items. Once the buffer
     is full, adding a new entry overrides the oldest entry.
 >
@@ -1890,28 +1985,28 @@ ringbuf({size})                                                *vim.ringbuf()*
     Return: ~
         (table)
 
-Ringbuf:clear()                                              *Ringbuf:clear()*
+vim.Ringbuf:clear()                                          *Ringbuf:clear()*
     Clear all items.
 
-Ringbuf:peek()                                                *Ringbuf:peek()*
+vim.Ringbuf:peek()                                            *Ringbuf:peek()*
     Returns the first unread item without removing it
 
     Return: ~
         any?|ni
 
-Ringbuf:pop()                                                  *Ringbuf:pop()*
+vim.Ringbuf:pop()                                              *Ringbuf:pop()*
     Removes and returns the first unread item
 
     Return: ~
         any?|ni
 
-Ringbuf:push({item})                                          *Ringbuf:push()*
+vim.Ringbuf:push({item})                                      *Ringbuf:push()*
     Adds an item, overriding the oldest item if the buffer is full.
 
     Parameters: ~
       • {item}  any
 
-spairs({t})                                                     *vim.spairs()*
+vim.spairs({t})                                                 *vim.spairs()*
     Enumerate a table sorted by its keys.
 
     Parameters: ~
@@ -1923,7 +2018,7 @@ spairs({t})                                                     *vim.spairs()*
     See also: ~
       • Based on https://github.com/premake/premake-core/blob/master/src/base/table.lua
 
-split({s}, {sep}, {opts})                                        *vim.split()*
+vim.split({s}, {sep}, {opts})                                    *vim.split()*
     Splits a string at each instance of a separator.
 
     Examples: >lua
@@ -1947,7 +2042,7 @@ split({s}, {sep}, {opts})                                        *vim.split()*
       • |vim.gsplit()|
       • |string.gmatch()|
 
-startswith({s}, {prefix})                                   *vim.startswith()*
+vim.startswith({s}, {prefix})                               *vim.startswith()*
     Tests if `s` starts with `prefix`.
 
     Parameters: ~
@@ -1957,7 +2052,7 @@ startswith({s}, {prefix})                                   *vim.startswith()*
     Return: ~
         (boolean) `true` if `prefix` is a prefix of `s`
 
-tbl_add_reverse_lookup({o})                     *vim.tbl_add_reverse_lookup()*
+vim.tbl_add_reverse_lookup({o})                 *vim.tbl_add_reverse_lookup()*
     Add the reverse lookup values to an existing table. For example:
     `tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A = 1 }`
 
@@ -1969,7 +2064,7 @@ tbl_add_reverse_lookup({o})                     *vim.tbl_add_reverse_lookup()*
     Return: ~
         (table) o
 
-tbl_contains({t}, {value}, {opts})                        *vim.tbl_contains()*
+vim.tbl_contains({t}, {value}, {opts})                    *vim.tbl_contains()*
     Checks if a table contains a given value, specified either directly or via
     a predicate that is checked for each value.
 
@@ -1994,7 +2089,7 @@ tbl_contains({t}, {value}, {opts})                        *vim.tbl_contains()*
     See also: ~
       • |vim.list_contains()| for checking values in list-like tables
 
-tbl_count({t})                                               *vim.tbl_count()*
+vim.tbl_count({t})                                           *vim.tbl_count()*
     Counts the number of non-nil values in table `t`.
 
     >lua
@@ -2012,7 +2107,7 @@ tbl_count({t})                                               *vim.tbl_count()*
     See also: ~
       • https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua
 
-tbl_deep_extend({behavior}, {...})                     *vim.tbl_deep_extend()*
+vim.tbl_deep_extend({behavior}, {...})                 *vim.tbl_deep_extend()*
     Merges recursively two or more tables.
 
     Parameters: ~
@@ -2029,7 +2124,7 @@ tbl_deep_extend({behavior}, {...})                     *vim.tbl_deep_extend()*
     See also: ~
       • |vim.tbl_extend()|
 
-tbl_extend({behavior}, {...})                               *vim.tbl_extend()*
+vim.tbl_extend({behavior}, {...})                           *vim.tbl_extend()*
     Merges two or more tables.
 
     Parameters: ~
@@ -2046,7 +2141,7 @@ tbl_extend({behavior}, {...})                               *vim.tbl_extend()*
     See also: ~
       • |extend()|
 
-tbl_filter({func}, {t})                                     *vim.tbl_filter()*
+vim.tbl_filter({func}, {t})                                 *vim.tbl_filter()*
     Filter a table using a predicate function
 
     Parameters: ~
@@ -2056,7 +2151,7 @@ tbl_filter({func}, {t})                                     *vim.tbl_filter()*
     Return: ~
         (table) Table of filtered values
 
-tbl_flatten({t})                                           *vim.tbl_flatten()*
+vim.tbl_flatten({t})                                       *vim.tbl_flatten()*
     Creates a copy of a list-like table such that any nested tables are
     "unrolled" and appended to the result.
 
@@ -2069,7 +2164,7 @@ tbl_flatten({t})                                           *vim.tbl_flatten()*
     See also: ~
       • From https://github.com/premake/premake-core/blob/master/src/base/table.lua
 
-tbl_get({o}, {...})                                            *vim.tbl_get()*
+vim.tbl_get({o}, {...})                                        *vim.tbl_get()*
     Index into a table (first argument) via string keys passed as subsequent
     arguments. Return `nil` if the key does not exist.
 
@@ -2087,7 +2182,7 @@ tbl_get({o}, {...})                                            *vim.tbl_get()*
     Return: ~
         any Nested value indexed by key (if it exists), else nil
 
-tbl_isarray({t})                                           *vim.tbl_isarray()*
+vim.tbl_isarray({t})                                       *vim.tbl_isarray()*
     Tests if a Lua table can be treated as an array (a table indexed by
     integers).
 
@@ -2101,7 +2196,7 @@ tbl_isarray({t})                                           *vim.tbl_isarray()*
     Return: ~
         (boolean) `true` if array-like table, else `false`.
 
-tbl_isempty({t})                                           *vim.tbl_isempty()*
+vim.tbl_isempty({t})                                       *vim.tbl_isempty()*
     Checks if a table is empty.
 
     Parameters: ~
@@ -2113,7 +2208,7 @@ tbl_isempty({t})                                           *vim.tbl_isempty()*
     See also: ~
       • https://github.com/premake/premake-core/blob/master/src/base/table.lua
 
-tbl_islist({t})                                             *vim.tbl_islist()*
+vim.tbl_islist({t})                                         *vim.tbl_islist()*
     Tests if a Lua table can be treated as a list (a table indexed by
     consecutive integers starting from 1).
 
@@ -2127,7 +2222,7 @@ tbl_islist({t})                                             *vim.tbl_islist()*
     Return: ~
         (boolean) `true` if list-like table, else `false`.
 
-tbl_keys({t})                                                 *vim.tbl_keys()*
+vim.tbl_keys({t})                                             *vim.tbl_keys()*
     Return a list of all keys used in a table. However, the order of the
     return table of keys is not guaranteed.
 
@@ -2140,7 +2235,7 @@ tbl_keys({t})                                                 *vim.tbl_keys()*
     See also: ~
       • From https://github.com/premake/premake-core/blob/master/src/base/table.lua
 
-tbl_map({func}, {t})                                           *vim.tbl_map()*
+vim.tbl_map({func}, {t})                                       *vim.tbl_map()*
     Apply a function to all values of a table.
 
     Parameters: ~
@@ -2150,7 +2245,7 @@ tbl_map({func}, {t})                                           *vim.tbl_map()*
     Return: ~
         (table) Table of transformed values
 
-tbl_values({t})                                             *vim.tbl_values()*
+vim.tbl_values({t})                                         *vim.tbl_values()*
     Return a list of all values used in a table. However, the order of the
     return table of values is not guaranteed.
 
@@ -2160,7 +2255,7 @@ tbl_values({t})                                             *vim.tbl_values()*
     Return: ~
         (list) List of values
 
-trim({s})                                                         *vim.trim()*
+vim.trim({s})                                                     *vim.trim()*
     Trim whitespace (Lua pattern "%s") from both sides of a string.
 
     Parameters: ~
@@ -2173,7 +2268,7 @@ trim({s})                                                         *vim.trim()*
       • |luaref-patterns|
       • https://www.lua.org/pil/20.2.html
 
-validate({opt})                                               *vim.validate()*
+vim.validate({opt})                                           *vim.validate()*
     Validates a parameter specification (types and values).
 
     Usage example: >lua
@@ -2229,21 +2324,21 @@ validate({opt})                                               *vim.validate()*
 
 
 ==============================================================================
-Lua module: loader                                                *lua-loader*
+Lua module: vim.loader                                            *lua-loader*
 
-disable()                                               *vim.loader.disable()*
+vim.loader.disable()                                    *vim.loader.disable()*
     Disables the experimental Lua module loader:
     • removes the loaders
     • adds the default Nvim loader
 
-enable()                                                 *vim.loader.enable()*
+vim.loader.enable()                                      *vim.loader.enable()*
     Enables the experimental Lua module loader:
     • overrides loadfile
     • adds the Lua loader using the byte-compilation cache
     • adds the libs loader
     • removes the default Nvim loader
 
-find({modname}, {opts})                                    *vim.loader.find()*
+vim.loader.find({modname}, {opts})                         *vim.loader.find()*
     Finds Lua modules for the given module name.
 
     Parameters: ~
@@ -2268,7 +2363,7 @@ find({modname}, {opts})                                    *vim.loader.find()*
         • stat: (table|nil) the fs_stat of the module path. Won't be returned
           for `modname="*"`
 
-reset({path})                                             *vim.loader.reset()*
+vim.loader.reset({path})                                  *vim.loader.reset()*
     Resets the cache for the path, or all the paths if path is nil.
 
     Parameters: ~
@@ -2276,9 +2371,9 @@ reset({path})                                             *vim.loader.reset()*
 
 
 ==============================================================================
-Lua module: uri                                                      *lua-uri*
+Lua module: vim.uri                                                  *lua-uri*
 
-uri_from_bufnr({bufnr})                                 *vim.uri_from_bufnr()*
+vim.uri_from_bufnr({bufnr})                             *vim.uri_from_bufnr()*
     Get a URI from a bufnr
 
     Parameters: ~
@@ -2287,7 +2382,7 @@ uri_from_bufnr({bufnr})                                 *vim.uri_from_bufnr()*
     Return: ~
         (string) URI
 
-uri_from_fname({path})                                  *vim.uri_from_fname()*
+vim.uri_from_fname({path})                              *vim.uri_from_fname()*
     Get a URI from a file path.
 
     Parameters: ~
@@ -2296,7 +2391,7 @@ uri_from_fname({path})                                  *vim.uri_from_fname()*
     Return: ~
         (string) URI
 
-uri_to_bufnr({uri})                                       *vim.uri_to_bufnr()*
+vim.uri_to_bufnr({uri})                                   *vim.uri_to_bufnr()*
     Get the buffer for a uri. Creates a new unloaded buffer if no buffer for
     the uri already exists.
 
@@ -2306,7 +2401,7 @@ uri_to_bufnr({uri})                                       *vim.uri_to_bufnr()*
     Return: ~
         (integer) bufnr
 
-uri_to_fname({uri})                                       *vim.uri_to_fname()*
+vim.uri_to_fname({uri})                                   *vim.uri_to_fname()*
     Get a filename from a URI
 
     Parameters: ~
@@ -2317,9 +2412,9 @@ uri_to_fname({uri})                                       *vim.uri_to_fname()*
 
 
 ==============================================================================
-Lua module: ui                                                        *lua-ui*
+Lua module: vim.ui                                                    *lua-ui*
 
-input({opts}, {on_confirm})                                   *vim.ui.input()*
+vim.ui.input({opts}, {on_confirm})                            *vim.ui.input()*
     Prompts the user for input, allowing arbitrary (potentially asynchronous)
     work until `on_confirm`.
 
@@ -2345,7 +2440,7 @@ input({opts}, {on_confirm})                                   *vim.ui.input()*
                       typed (it might be an empty string if nothing was
                       entered), or `nil` if the user aborted the dialog.
 
-open({path})                                                   *vim.ui.open()*
+vim.ui.open({path})                                            *vim.ui.open()*
     Opens `path` with the system default handler (macOS `open`, Windows
     `explorer.exe`, Linux `xdg-open`, …), or returns (but does not show) an
     error message on failure.
@@ -2369,7 +2464,7 @@ open({path})                                                   *vim.ui.open()*
     See also: ~
       • |vim.system()|
 
-select({items}, {opts}, {on_choice})                         *vim.ui.select()*
+vim.ui.select({items}, {opts}, {on_choice})                  *vim.ui.select()*
     Prompts the user to pick from a list of items, allowing arbitrary
     (potentially asynchronous) work until `on_choice`.
 
@@ -2407,9 +2502,9 @@ select({items}, {opts}, {on_choice})                         *vim.ui.select()*
 
 
 ==============================================================================
-Lua module: filetype                                            *lua-filetype*
+Lua module: vim.filetype                                        *lua-filetype*
 
-add({filetypes})                                          *vim.filetype.add()*
+vim.filetype.add({filetypes})                             *vim.filetype.add()*
     Add new filetype mappings.
 
     Filetype mappings can be added either by extension or by filename (either
@@ -2495,7 +2590,8 @@ add({filetypes})                                          *vim.filetype.add()*
       • {filetypes}  (table) A table containing new filetype maps (see
                      example).
 
-get_option({filetype}, {option})                   *vim.filetype.get_option()*
+                                                   *vim.filetype.get_option()*
+vim.filetype.get_option({filetype}, {option})
     Get the default option value for a {filetype}.
 
     The returned value is what would be set in a new buffer after 'filetype'
@@ -2518,7 +2614,7 @@ get_option({filetype}, {option})                   *vim.filetype.get_option()*
     Return: ~
         string|boolean|integer: Option value
 
-match({args})                                           *vim.filetype.match()*
+vim.filetype.match({args})                              *vim.filetype.match()*
     Perform filetype detection.
 
     The filetype can be detected using one of three methods:
@@ -2574,9 +2670,9 @@ match({args})                                           *vim.filetype.match()*
 
 
 ==============================================================================
-Lua module: keymap                                                *lua-keymap*
+Lua module: vim.keymap                                            *lua-keymap*
 
-del({modes}, {lhs}, {opts})                                 *vim.keymap.del()*
+vim.keymap.del({modes}, {lhs}, {opts})                      *vim.keymap.del()*
     Remove an existing mapping. Examples: >lua
 
        vim.keymap.del('n', 'lhs')
@@ -2592,7 +2688,7 @@ del({modes}, {lhs}, {opts})                                 *vim.keymap.del()*
     See also: ~
       • |vim.keymap.set()|
 
-set({mode}, {lhs}, {rhs}, {opts})                           *vim.keymap.set()*
+vim.keymap.set({mode}, {lhs}, {rhs}, {opts})                *vim.keymap.set()*
     Adds a new |mapping|. Examples: >lua
 
        -- Map to a Lua function:
@@ -2634,9 +2730,9 @@ set({mode}, {lhs}, {rhs}, {opts})                           *vim.keymap.set()*
 
 
 ==============================================================================
-Lua module: fs                                                        *lua-fs*
+Lua module: vim.fs                                                    *lua-fs*
 
-basename({file})                                           *vim.fs.basename()*
+vim.fs.basename({file})                                    *vim.fs.basename()*
     Return the basename of the given file or directory
 
     Parameters: ~
@@ -2645,7 +2741,7 @@ basename({file})                                           *vim.fs.basename()*
     Return: ~
         (string|nil) Basename of {file}
 
-dir({path}, {opts})                                             *vim.fs.dir()*
+vim.fs.dir({path}, {opts})                                      *vim.fs.dir()*
     Return an iterator over the files and directories located in {path}
 
     Parameters: ~
@@ -2663,7 +2759,7 @@ dir({path}, {opts})                                             *vim.fs.dir()*
         two values: name and type. Each "name" is the basename of the file or
         directory relative to {path}. Type is one of "file" or "directory".
 
-dirname({file})                                             *vim.fs.dirname()*
+vim.fs.dirname({file})                                      *vim.fs.dirname()*
     Return the parent directory of the given file or directory
 
     Parameters: ~
@@ -2672,7 +2768,7 @@ dirname({file})                                             *vim.fs.dirname()*
     Return: ~
         (string|nil) Parent directory of {file}
 
-find({names}, {opts})                                          *vim.fs.find()*
+vim.fs.find({names}, {opts})                                   *vim.fs.find()*
     Find files or directories in the given path.
 
     Finds any files or directories given in {names} starting from {path}. If
@@ -2734,7 +2830,7 @@ find({names}, {opts})                                          *vim.fs.find()*
         (table) Normalized paths |vim.fs.normalize()| of all matching files or
         directories
 
-joinpath({...})                                            *vim.fs.joinpath()*
+vim.fs.joinpath({...})                                     *vim.fs.joinpath()*
     Concatenate directories and/or file paths into a single path with
     normalization (e.g., `"foo/"` and `"bar"` get joined to `"foo/bar"`)
 
@@ -2744,7 +2840,7 @@ joinpath({...})                                            *vim.fs.joinpath()*
     Return: ~
         (string)
 
-normalize({path}, {opts})                                 *vim.fs.normalize()*
+vim.fs.normalize({path}, {opts})                          *vim.fs.normalize()*
     Normalize a path to a standard format. A tilde (~) character at the
     beginning of the path is expanded to the user's home directory and any
     backslash (\) characters are converted to forward slashes (/). Environment
@@ -2771,7 +2867,7 @@ normalize({path}, {opts})                                 *vim.fs.normalize()*
     Return: ~
         (string) Normalized path
 
-parents({start})                                            *vim.fs.parents()*
+vim.fs.parents({start})                                     *vim.fs.parents()*
     Iterate over all the parents of the given file or directory.
 
     Example: >lua
@@ -2797,9 +2893,9 @@ parents({start})                                            *vim.fs.parents()*
 
 
 ==============================================================================
-Lua module: secure                                                *lua-secure*
+Lua module: vim.secure                                            *lua-secure*
 
-read({path})                                               *vim.secure.read()*
+vim.secure.read({path})                                    *vim.secure.read()*
     Attempt to read the file at {path} prompting the user if the file should
     be trusted. The user's choice is persisted in a trust database at
     $XDG_STATE_HOME/nvim/trust.
@@ -2814,7 +2910,7 @@ read({path})                                               *vim.secure.read()*
     See also: ~
       • |:trust|
 
-trust({opts})                                             *vim.secure.trust()*
+vim.secure.trust({opts})                                  *vim.secure.trust()*
     Manage the trust database.
 
     The trust database is located at |$XDG_STATE_HOME|/nvim/trust.
@@ -2837,7 +2933,7 @@ trust({opts})                                             *vim.secure.trust()*
 
 
 ==============================================================================
-Lua module: version                                              *lua-version*
+Lua module: vim.version                                          *lua-version*
 
 
 The `vim.version` module provides functions for comparing versions and
@@ -2897,7 +2993,7 @@ versions (1.2.3-rc1) are not matched. >
 
 <
 
-cmp({v1}, {v2})                                            *vim.version.cmp()*
+vim.version.cmp({v1}, {v2})                                *vim.version.cmp()*
     Parses and compares two version objects (the result of
     |vim.version.parse()|, or specified literally as a `{major, minor, patch}`
     tuple, e.g. `{1, 0, 3}`).
@@ -2925,7 +3021,7 @@ cmp({v1}, {v2})                                            *vim.version.cmp()*
     Return: ~
         (integer) -1 if `v1 < v2`, 0 if `v1 == v2`, 1 if `v1 > v2`.
 
-eq({v1}, {v2})                                              *vim.version.eq()*
+vim.version.eq({v1}, {v2})                                  *vim.version.eq()*
     Returns `true` if the given versions are equal. See |vim.version.cmp()| for usage.
 
     Parameters: ~
@@ -2935,7 +3031,7 @@ eq({v1}, {v2})                                              *vim.version.eq()*
     Return: ~
         (boolean)
 
-gt({v1}, {v2})                                              *vim.version.gt()*
+vim.version.gt({v1}, {v2})                                  *vim.version.gt()*
     Returns `true` if `v1 > v2` . See |vim.version.cmp()| for usage.
 
     Parameters: ~
@@ -2945,7 +3041,7 @@ gt({v1}, {v2})                                              *vim.version.gt()*
     Return: ~
         (boolean)
 
-last({versions})                                          *vim.version.last()*
+vim.version.last({versions})                              *vim.version.last()*
     TODO: generalize this, move to func.lua
 
     Parameters: ~
@@ -2954,7 +3050,7 @@ last({versions})                                          *vim.version.last()*
     Return: ~
         Version ?|ni
 
-lt({v1}, {v2})                                              *vim.version.lt()*
+vim.version.lt({v1}, {v2})                                  *vim.version.lt()*
     Returns `true` if `v1 < v2` . See |vim.version.cmp()| for usage.
 
     Parameters: ~
@@ -2964,7 +3060,7 @@ lt({v1}, {v2})                                              *vim.version.lt()*
     Return: ~
         (boolean)
 
-parse({version}, {opts})                                 *vim.version.parse()*
+vim.version.parse({version}, {opts})                     *vim.version.parse()*
     Parses a semantic version string and returns a version object which can be
     used with other `vim.version` functions. For example "1.0.1-rc1+build.2" returns: >
 
@@ -2985,7 +3081,7 @@ parse({version}, {opts})                                 *vim.version.parse()*
     See also: ~
       • # https://semver.org/spec/v2.0.0.html
 
-range({spec})                                            *vim.version.range()*
+vim.version.range({spec})                                *vim.version.range()*
     Parses a semver |version-range| "spec" and returns a range object: >
 
        {
@@ -3020,7 +3116,7 @@ range({spec})                                            *vim.version.range()*
 
 
 ==============================================================================
-Lua module: iter                                                    *lua-iter*
+Lua module: vim.iter                                                *lua-iter*
 
 
 The *vim.iter* module provides a generic interface for working with
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
diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua
index 41e6e8be86..d498ae0a2c 100644
--- a/runtime/lua/vim/_options.lua
+++ b/runtime/lua/vim/_options.lua
@@ -1,3 +1,108 @@
+---@defgroup lua-vimscript
+---
+---@brief Nvim Lua provides an interface or "bridge" to Vimscript variables and
+---functions, and editor commands and options.
+---
+---Objects passed over this bridge are COPIED (marshalled): there are no
+---"references". |lua-guide-variables| For example, using \`vim.fn.remove()\` on
+---a Lua list copies the list object to Vimscript and does NOT modify the Lua
+---list:
+---<pre>lua
+---    local list = { 1, 2, 3 }
+---    vim.fn.remove(list, 0)
+---    vim.print(list)  --> "{ 1, 2, 3 }"
+---</pre>
+
+---@addtogroup lua-vimscript
+---@brief <pre>help
+---vim.call({func}, {...})                                           *vim.call()*
+---    Invokes |vim-function| or |user-function| {func} with arguments {...}.
+---    See also |vim.fn|.
+---    Equivalent to: >lua
+---        vim.fn[func]({...})
+---<
+---vim.cmd({command})
+---    See |vim.cmd()|.
+---
+---vim.fn.{func}({...})                                                  *vim.fn*
+---    Invokes |vim-function| or |user-function| {func} with arguments {...}.
+---    To call autoload functions, use the syntax: >lua
+---        vim.fn['some\#function']({...})
+---<
+---    Unlike vim.api.|nvim_call_function()| this converts directly between Vim
+---    objects and Lua objects. If the Vim function returns a float, it will be
+---    represented directly as a Lua number. Empty lists and dictionaries both
+---    are represented by an empty table.
+---
+---    Note: |v:null| values as part of the return value is represented as
+---    |vim.NIL| special value
+---
+---    Note: vim.fn keys are generated lazily, thus `pairs(vim.fn)` only
+---    enumerates functions that were called at least once.
+---
+---    Note: The majority of functions cannot run in |api-fast| callbacks with some
+---    undocumented exceptions which are allowed.
+---
+---                                                           *lua-vim-variables*
+---The Vim editor global dictionaries |g:| |w:| |b:| |t:| |v:| can be accessed
+---from Lua conveniently and idiomatically by referencing the `vim.*` Lua tables
+---described below. In this way you can easily read and modify global Vimscript
+---variables from Lua.
+---
+---Example: >lua
+---
+---    vim.g.foo = 5     -- Set the g:foo Vimscript variable.
+---    print(vim.g.foo)  -- Get and print the g:foo Vimscript variable.
+---    vim.g.foo = nil   -- Delete (:unlet) the Vimscript variable.
+---    vim.b[2].foo = 6  -- Set b:foo for buffer 2
+---<
+---
+---Note that setting dictionary fields directly will not write them back into
+---Nvim. This is because the index into the namespace simply returns a copy.
+---Instead the whole dictionary must be written as one. This can be achieved by
+---creating a short-lived temporary.
+---
+---Example: >lua
+---
+---    vim.g.my_dict.field1 = 'value'  -- Does not work
+---
+---    local my_dict = vim.g.my_dict   --
+---    my_dict.field1 = 'value'        -- Instead do
+---    vim.g.my_dict = my_dict         --
+---
+---vim.g                                                                  *vim.g*
+---    Global (|g:|) editor variables.
+---    Key with no value returns `nil`.
+---
+---vim.b                                                                  *vim.b*
+---    Buffer-scoped (|b:|) variables for the current buffer.
+---    Invalid or unset key returns `nil`. Can be indexed with
+---    an integer to access variables for a specific buffer.
+---
+---vim.w                                                                  *vim.w*
+---    Window-scoped (|w:|) variables for the current window.
+---    Invalid or unset key returns `nil`. Can be indexed with
+---    an integer to access variables for a specific window.
+---
+---vim.t                                                                  *vim.t*
+---    Tabpage-scoped (|t:|) variables for the current tabpage.
+---    Invalid or unset key returns `nil`. Can be indexed with
+---    an integer to access variables for a specific tabpage.
+---
+---vim.v                                                                  *vim.v*
+---    |v:| variables.
+---    Invalid or unset key returns `nil`.
+---
+---vim.env                                                              *vim.env*
+---    Environment variables defined in the editor session.
+---    See |expand-env| and |:let-environment| for the Vimscript behavior.
+---    Invalid or unset key returns `nil`.
+---    Example: >lua
+---        vim.env.FOO = 'bar'
+---        print(vim.env.TERM)
+---<
+---</pre>
+
 local api = vim.api
 
 -- TODO(tjdevries): Improve option metadata so that this doesn't have to be hardcoded.
@@ -13,6 +118,7 @@ local key_value_options = {
 
 --- Convert a vimoption_T style dictionary to the correct OptionType associated with it.
 ---@return string
+---@private
 local function get_option_metatype(name, info)
   if info.type == 'string' then
     if info.flaglist then
@@ -51,6 +157,7 @@ vim.env = setmetatable({}, {
   end,
 })
 
+---@private
 local function opt_validate(option_name, target_scope)
   local scope = options_info[option_name].scope
   if scope ~= target_scope then
@@ -67,6 +174,7 @@ local function opt_validate(option_name, target_scope)
   end
 end
 
+---@private
 local function new_buf_opt_accessor(bufnr)
   return setmetatable({}, {
     __index = function(_, k)
@@ -84,8 +192,7 @@ local function new_buf_opt_accessor(bufnr)
   })
 end
 
-vim.bo = new_buf_opt_accessor()
-
+---@private
 local function new_win_opt_accessor(winid, bufnr)
   return setmetatable({}, {
     __index = function(_, k)
@@ -120,30 +227,118 @@ local function new_win_opt_accessor(winid, bufnr)
   })
 end
 
-vim.wo = new_win_opt_accessor()
-
--- vim global option
---  this ONLY sets the global option. like `setglobal`
-vim.go = setmetatable({}, {
+---@addtogroup lua-vimscript
+---@brief <pre>help
+---` `                                                                *lua-options*
+---                                                             *lua-vim-options*
+---                                                                 *lua-vim-set*
+---                                                            *lua-vim-setlocal*
+---
+---Vim options can be accessed through |vim.o|, which behaves like Vimscript
+---|:set|.
+---
+---    Examples: ~
+---
+---    To set a boolean toggle:
+---        Vimscript: `set number`
+---        Lua:       `vim.o.number = true`
+---
+---    To set a string value:
+---        Vimscript: `set wildignore=*.o,*.a,__pycache__`
+---        Lua:       `vim.o.wildignore = '*.o,*.a,__pycache__'`
+---
+---Similarly, there is |vim.bo| and |vim.wo| for setting buffer-scoped and
+---window-scoped options. Note that this must NOT be confused with
+---|local-options| and |:setlocal|. There is also |vim.go| that only accesses the
+---global value of a |global-local| option, see |:setglobal|.
+---</pre>
+
+---@addtogroup lua-vimscript
+---@brief <pre>help
+---vim.o                                                                  *vim.o*
+---    Get or set |options|. Like `:set`. Invalid key is an error.
+---
+---    Note: this works on both buffer-scoped and window-scoped options using the
+---    current buffer and window.
+---
+---    Example: >lua
+---        vim.o.cmdheight = 4
+---        print(vim.o.columns)
+---        print(vim.o.foo)     -- error: invalid key
+---<
+---</pre>
+vim.o = setmetatable({}, {
   __index = function(_, k)
-    return api.nvim_get_option_value(k, { scope = 'global' })
+    return api.nvim_get_option_value(k, {})
   end,
   __newindex = function(_, k, v)
-    return api.nvim_set_option_value(k, v, { scope = 'global' })
+    return api.nvim_set_option_value(k, v, {})
   end,
 })
 
--- vim `set` style options.
---  it has no additional metamethod magic.
-vim.o = setmetatable({}, {
+---@addtogroup lua-vimscript
+---@brief <pre>help
+---vim.go                                                                *vim.go*
+---    Get or set global |options|. Like `:setglobal`. Invalid key is
+---    an error.
+---
+---    Note: this is different from |vim.o| because this accesses the global
+---    option value and thus is mostly useful for use with |global-local|
+---    options.
+---
+---    Example: >lua
+---        vim.go.cmdheight = 4
+---        print(vim.go.columns)
+---        print(vim.go.bar)     -- error: invalid key
+---<
+---</pre>
+vim.go = setmetatable({}, {
   __index = function(_, k)
-    return api.nvim_get_option_value(k, {})
+    return api.nvim_get_option_value(k, { scope = 'global' })
   end,
   __newindex = function(_, k, v)
-    return api.nvim_set_option_value(k, v, {})
+    return api.nvim_set_option_value(k, v, { scope = 'global' })
   end,
 })
 
+---@addtogroup lua-vimscript
+---@brief <pre>help
+---vim.bo[{bufnr}]                                                                *vim.bo*
+---    Get or set buffer-scoped |options| for the buffer with number {bufnr}.
+---    Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current
+---    buffer is used. Invalid {bufnr} or key is an error.
+---
+---    Note: this is equivalent to both `:set` and `:setlocal`.
+---
+---    Example: >lua
+---        local bufnr = vim.api.nvim_get_current_buf()
+---        vim.bo[bufnr].buflisted = true    -- same as vim.bo.buflisted = true
+---        print(vim.bo.comments)
+---        print(vim.bo.baz)                 -- error: invalid key
+---</pre>
+vim.bo = new_buf_opt_accessor()
+
+---@addtogroup lua-vimscript
+---@brief <pre>help
+---vim.wo[{winid}][{bufnr}]                                                       *vim.wo*
+---    Get or set window-scoped |options| for the window with handle {winid} and
+---    buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like
+---    `:set` otherwise. If [{winid}] is omitted then the current window is
+---    used. Invalid {winid}, {bufnr} or key is an error.
+---
+---    Note: only {bufnr} with value `0` (the current buffer in the window) is
+---    supported.
+---
+---    Example: >lua
+---        local winid = vim.api.nvim_get_current_win()
+---        vim.wo[winid].number = true    -- same as vim.wo.number = true
+---        print(vim.wo.foldmarker)
+---        print(vim.wo.quux)             -- error: invalid key
+---        vim.wo[winid][0].spell = false -- like ':setlocal nospell'
+---<
+---</pre>
+vim.wo = new_win_opt_accessor()
+
 ---@brief [[
 --- vim.opt, vim.opt_local and vim.opt_global implementation
 ---
@@ -153,6 +348,7 @@ vim.o = setmetatable({}, {
 ---@brief ]]
 
 --- Preserves the order and does not mutate the original list
+--- @private
 local function remove_duplicate_values(t)
   local result, seen = {}, {}
   for _, v in ipairs(t) do
@@ -168,6 +364,7 @@ end
 
 -- Check whether the OptionTypes is allowed for vim.opt
 -- If it does not match, throw an error which indicates which option causes the error.
+--- @private
 local function assert_valid_value(name, value, types)
   local type_of_value = type(value)
   for _, valid_type in ipairs(types) do
@@ -186,14 +383,17 @@ local function assert_valid_value(name, value, types)
   )
 end
 
+--- @private
 local function passthrough(_, x)
   return x
 end
 
+--- @private
 local function tbl_merge(left, right)
   return vim.tbl_extend('force', left, right)
 end
 
+--- @private
 local function tbl_remove(t, value)
   if type(value) == 'string' then
     t[value] = nil
@@ -275,6 +475,7 @@ local to_vim_value = {
 }
 
 --- Convert a Lua value to a vimoption_T value
+--- @private
 local function convert_value_to_vim(name, info, value)
   if value == nil then
     return vim.NIL
@@ -390,6 +591,7 @@ local to_lua_value = {
 }
 
 --- Converts a vimoption_T style value to a Lua value
+--- @private
 local function convert_value_to_lua(info, option_value)
   return to_lua_value[info.metatype](info, option_value)
 end
@@ -416,6 +618,7 @@ local prepend_methods = {
 }
 
 --- Handles the '^' operator
+--- @private
 local function prepend_value(info, current, new)
   return prepend_methods[info.metatype](
     convert_value_to_lua(info, current),
@@ -445,6 +648,7 @@ local add_methods = {
 }
 
 --- Handles the '+' operator
+--- @private
 local function add_value(info, current, new)
   return add_methods[info.metatype](
     convert_value_to_lua(info, current),
@@ -452,6 +656,7 @@ local function add_value(info, current, new)
   )
 end
 
+--- @private
 local function remove_one_item(t, val)
   if vim.tbl_islist(t) then
     local remove_index = nil
@@ -495,13 +700,16 @@ local remove_methods = {
 }
 
 --- Handles the '-' operator
+--- @private
 local function remove_value(info, current, new)
   return remove_methods[info.metatype](convert_value_to_lua(info, current), new)
 end
 
+--- @private
 local function create_option_accessor(scope)
   local option_mt
 
+  --- @private
   local function make_option(name, value)
     local info = assert(options_info[name], 'Not a valid option name: ' .. name)
 
@@ -570,6 +778,151 @@ local function create_option_accessor(scope)
   })
 end
 
+---@addtogroup lua-vimscript
+---@brief <pre>help
+---` `                                                                       *vim.opt_local*
+---                                                                       *vim.opt_global*
+---                                                                              *vim.opt*
+---
+---
+---A special interface |vim.opt| exists for conveniently interacting with list-
+---and map-style option from Lua: It allows accessing them as Lua tables and
+---offers object-oriented method for adding and removing entries.
+---
+---    Examples: ~
+---
+---    The following methods of setting a list-style option are equivalent:
+---        In Vimscript: >vim
+---            set wildignore=*.o,*.a,__pycache__
+---<
+---        In Lua using `vim.o`: >lua
+---            vim.o.wildignore = '*.o,*.a,__pycache__'
+---<
+---        In Lua using `vim.opt`: >lua
+---            vim.opt.wildignore = { '*.o', '*.a', '__pycache__' }
+---<
+---    To replicate the behavior of |:set+=|, use: >lua
+---
+---        vim.opt.wildignore:append { "*.pyc", "node_modules" }
+---<
+---    To replicate the behavior of |:set^=|, use: >lua
+---
+---        vim.opt.wildignore:prepend { "new_first_value" }
+---<
+---    To replicate the behavior of |:set-=|, use: >lua
+---
+---        vim.opt.wildignore:remove { "node_modules" }
+---<
+---    The following methods of setting a map-style option are equivalent:
+---        In Vimscript: >vim
+---            set listchars=space:_,tab:>~
+---<
+---        In Lua using `vim.o`: >lua
+---            vim.o.listchars = 'space:_,tab:>~'
+---<
+---        In Lua using `vim.opt`: >lua
+---            vim.opt.listchars = { space = '_', tab = '>~' }
+---<
+---
+---Note that |vim.opt| returns an `Option` object, not the value of the option,
+---which is accessed through |vim.opt:get()|:
+---
+---    Examples: ~
+---
+---    The following methods of getting a list-style option are equivalent:
+---        In Vimscript: >vim
+---            echo wildignore
+---<
+---        In Lua using `vim.o`: >lua
+---            print(vim.o.wildignore)
+---<
+---        In Lua using `vim.opt`: >lua
+---            vim.print(vim.opt.wildignore:get())
+---<
+---
+---In any of the above examples, to replicate the behavior |:setlocal|, use
+---`vim.opt_local`. Additionally, to replicate the behavior of |:setglobal|, use
+---`vim.opt_global`.
+---</pre>
+
+--- @diagnostic disable-next-line:unused-local used for gen_vimdoc
+local Option = {}
+
+---Returns a Lua-representation of the option. Boolean, number and string
+---values will be returned in exactly the same fashion.
+---
+---For values that are comma-separated lists, an array will be returned with
+---the values as entries in the array: <pre>lua
+---    vim.cmd [[set wildignore=*.pyc,*.o]]
+---
+---    vim.print(vim.opt.wildignore:get())
+---    -- { "*.pyc", "*.o", }
+---
+---    for _, ignore_pattern in ipairs(vim.opt.wildignore:get()) do
+---        print("Will ignore:", ignore_pattern)
+---    end
+---    -- Will ignore: *.pyc
+---    -- Will ignore: *.o
+---</pre>
+---
+---For values that are comma-separated maps, a table will be returned with
+---the names as keys and the values as entries: <pre>lua
+---    vim.cmd [[set listchars=space:_,tab:>~]]
+---
+---    vim.print(vim.opt.listchars:get())
+---    --  { space = "_", tab = ">~", }
+---
+---    for char, representation in pairs(vim.opt.listchars:get()) do
+---        print(char, "=>", representation)
+---    end
+---</pre>
+---
+---For values that are lists of flags, a set will be returned with the flags
+---as keys and `true` as entries. <pre>lua
+---    vim.cmd [[set formatoptions=njtcroql]]
+---
+---    vim.print(vim.opt.formatoptions:get())
+---    -- { n = true, j = true, c = true, ... }
+---
+---    local format_opts = vim.opt.formatoptions:get()
+---    if format_opts.j then
+---        print("J is enabled!")
+---    end
+---</pre>
+---@return string|integer|boolean|nil value of option
+---@diagnostic disable-next-line:unused-local used for gen_vimdoc
+function Option:get() end
+
+---Append a value to string-style options. See |:set+=|
+---
+---These are equivalent: <pre>lua
+---    vim.opt.formatoptions:append('j')
+---    vim.opt.formatoptions = vim.opt.formatoptions + 'j'
+---</pre>
+---@param value string Value to append
+--- @diagnostic disable-next-line:unused-local used for gen_vimdoc
+function Option:append(value) end
+
+---Prepend a value to string-style options. See |:set^=|
+---
+---These are equivalent: <pre>lua
+---    vim.opt.wildignore:prepend('*.o')
+---    vim.opt.wildignore = vim.opt.wildignore ^ '*.o'
+---</pre>
+---@param value string Value to prepend
+---@diagnostic disable-next-line:unused-local used for gen_vimdoc
+function Option:prepend(value) end
+
+---Remove a value from string-style options. See |:set-=|
+---
+---These are equivalent: <pre>lua
+---    vim.opt.wildignore:remove('*.pyc')
+---    vim.opt.wildignore = vim.opt.wildignore - '*.pyc'
+---</pre>
+---@param value string Value to remove
+---@diagnostic disable-next-line:unused-local used for gen_vimdoc
+function Option:remove(value) end
+
 vim.opt = create_option_accessor()
 vim.opt_local = create_option_accessor('local')
 vim.opt_global = create_option_accessor('global')
diff --git a/runtime/lua/vim/highlight.lua b/runtime/lua/vim/highlight.lua
index 86e1adb49e..97a5a1233f 100644
--- a/runtime/lua/vim/highlight.lua
+++ b/runtime/lua/vim/highlight.lua
@@ -1,3 +1,36 @@
+---@defgroup lua-highlight
+---
+---@brief
+---Nvim includes a function for highlighting a selection on yank.
+---
+---To enable it, add the following to your `init.vim`:
+---<pre>vim
+---    au TextYankPost * silent! lua vim.highlight.on_yank()
+---</pre>
+---
+---You can customize the highlight group and the duration of
+---the highlight via:
+---<pre>vim
+---    au TextYankPost * silent! lua vim.highlight.on_yank {higroup="IncSearch", timeout=150}
+---</pre>
+---
+---If you want to exclude visual selections from highlighting on yank, use:
+---<pre>vim
+---    au TextYankPost * silent! lua vim.highlight.on_yank {on_visual=false}
+---</pre>
+---
+--- <pre>help
+---vim.highlight.priorities                            *vim.highlight.priorities*
+---
+---    Table with default priorities used for highlighting:
+---        • `syntax`: `50`, used for standard syntax highlighting
+---        • `treesitter`: `100`, used for tree-sitter-based highlighting
+---        • `semantic_tokens`: `125`, used for LSP semantic token highlighting
+---        • `diagnostics`: `150`, used for code analysis such as diagnostics
+---        • `user`: `200`, used for user-triggered highlights such as LSP document
+---          symbols or `on_yank` autocommands
+---</pre>
+
 local api = vim.api
 
 local M = {}
@@ -10,7 +43,7 @@ M.priorities = {
   user = 200,
 }
 
---- Highlight range between two positions
+--- Apply highlight group to range of text.
 ---
 ---@param bufnr integer Buffer number to apply highlighting to
 ---@param ns integer Namespace to add highlight to
@@ -18,9 +51,9 @@ M.priorities = {
 ---@param start integer[]|string Start of region as a (line, column) tuple or string accepted by |getpos()|
 ---@param finish integer[]|string End of region as a (line, column) tuple or string accepted by |getpos()|
 ---@param 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)
+---            - 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)
 function M.range(bufnr, ns, higroup, start, finish, opts)
   opts = opts or {}
   local regtype = opts.regtype or 'v'
@@ -46,22 +79,16 @@ end
 
 local yank_ns = api.nvim_create_namespace('hlyank')
 local yank_timer
---- Highlight the yanked region
----
---- use from init.vim via
----   au TextYankPost * lua vim.highlight.on_yank()
---- customize highlight group and timeout via
----   au TextYankPost * lua vim.highlight.on_yank {higroup="IncSearch", timeout=150}
---- customize conditions (here: do not highlight a visual selection) via
----   au TextYankPost * lua vim.highlight.on_yank {on_visual=false}
+
+--- Highlight the yanked text
 ---
--- @param 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`)
+--- @param 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`)
 function M.on_yank(opts)
   vim.validate({
     opts = {
diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py
index 6ca330ae22..eacf4dc24d 100755
--- a/scripts/gen_vimdoc.py
+++ b/scripts/gen_vimdoc.py
@@ -144,6 +144,14 @@ CONFIG = {
         'mode': 'lua',
         'filename': 'lua.txt',
         'section_order': [
+            'highlight.lua',
+            'regex.lua',
+            'diff.lua',
+            'mpack.lua',
+            'json.lua',
+            'spell.lua',
+            'builtin.lua',
+            '_options.lua',
             '_editor.lua',
             '_inspector.lua',
             'shared.lua',
@@ -160,6 +168,7 @@ CONFIG = {
         'files': [
             'runtime/lua/vim/iter.lua',
             'runtime/lua/vim/_editor.lua',
+            'runtime/lua/vim/_options.lua',
             'runtime/lua/vim/shared.lua',
             'runtime/lua/vim/loader.lua',
             'runtime/lua/vim/uri.lua',
@@ -167,30 +176,48 @@ CONFIG = {
             'runtime/lua/vim/filetype.lua',
             'runtime/lua/vim/keymap.lua',
             'runtime/lua/vim/fs.lua',
+            'runtime/lua/vim/highlight.lua',
             'runtime/lua/vim/secure.lua',
             'runtime/lua/vim/version.lua',
             'runtime/lua/vim/_inspector.lua',
+            'runtime/lua/vim/_meta/builtin.lua',
+            'runtime/lua/vim/_meta/diff.lua',
+            'runtime/lua/vim/_meta/mpack.lua',
+            'runtime/lua/vim/_meta/json.lua',
+            'runtime/lua/vim/_meta/regex.lua',
+            'runtime/lua/vim/_meta/spell.lua',
         ],
         'file_patterns': '*.lua',
         'fn_name_prefix': '',
+        'fn_name_fmt': lambda fstem, name: (
+            name if fstem in [ 'vim.iter' ] else
+            f'vim.{name}' if fstem in [ '_editor', 'vim.regex'] else
+            f'{fstem}.{name}' if fstem.startswith('vim') else
+            name
+        ),
         'section_name': {
             'lsp.lua': 'core',
             '_inspector.lua': 'inspector',
         },
         'section_fmt': lambda name: (
-            'Lua module: vim'
-            if name.lower() == '_editor'
-            else f'Lua module: {name.lower()}'),
+            'Lua module: vim' if name.lower() == '_editor' else
+            'LUA-VIMSCRIPT BRIDGE' if name.lower() == '_options' else
+            f'VIM.{name.upper()}' if name.lower() in [ 'highlight', 'mpack', 'json', 'diff', 'spell', 'regex' ] else
+            'VIM' if name.lower() == 'builtin' else
+            f'Lua module: vim.{name.lower()}'),
         'helptag_fmt': lambda name: (
-            '*lua-vim*'
-            if name.lower() == '_editor'
-            else f'*lua-{name.lower()}*'),
+            '*lua-vim*' if name.lower() == '_editor' else
+            '*lua-vimscript*' if name.lower() == '_options' else
+            f'*lua-{name.lower()}*'),
         'fn_helptag_fmt': lambda fstem, name: (
-            f'*vim.{name}()*'
-            if fstem.lower() == '_editor'
-            else f'*{name}()*'
-            if name[0].isupper()
-            else f'*{fstem}.{name}()*'),
+            f'*vim.opt:{name.split(":")[-1]}()*' if ':' in name and name.startswith('Option') else
+            # Exclude fstem for methods
+            f'*{name}()*' if ':' in name else
+            f'*vim.{name}()*' if fstem.lower() == '_editor' else
+            # Prevents vim.regex.regex
+            f'*{fstem}()*' if fstem.endswith('.' + name) else
+            f'*{fstem}.{name}()*'
+            ),
         'module_override': {
             # `shared` functions are exposed on the `vim` module.
             'shared': 'vim',
@@ -201,9 +228,16 @@ CONFIG = {
             'filetype': 'vim.filetype',
             'keymap': 'vim.keymap',
             'fs': 'vim.fs',
+            'highlight': 'vim.highlight',
             'secure': 'vim.secure',
             'version': 'vim.version',
             'iter': 'vim.iter',
+            'diff': 'vim',
+            'builtin': 'vim',
+            'mpack': 'vim.mpack',
+            'json': 'vim.json',
+            'regex': 'vim.regex',
+            'spell': 'vim.spell',
         },
         'append_only': [
             'shared.lua',
@@ -542,6 +576,8 @@ def render_node(n, text, prefix='', indent='', width=text_width - indentation,
             text += '>lua{}{}\n<'.format(ensure_nl, o[3:-1])
         elif o[0:4] == 'vim\n':
             text += '>vim{}{}\n<'.format(ensure_nl, o[3:-1])
+        elif o[0:5] == 'help\n':
+            text += o[4:-1]
         else:
             text += '>{}{}\n<'.format(ensure_nl, o)
 
@@ -869,6 +905,9 @@ def extract_from_xml(filename, target, width, fmt_vimhelp):
                 fstem = CONFIG[target]['module_override'].get(fstem, fstem)
             vimtag = CONFIG[target]['fn_helptag_fmt'](fstem, name)
 
+            if 'fn_name_fmt' in CONFIG[target]:
+                name = CONFIG[target]['fn_name_fmt'](fstem, name)
+
         prefix = '%s(' % name
         suffix = '%s)' % ', '.join('{%s}' % a[1] for a in params
                                    if a[0] not in ('void', 'Error', 'Arena',