fix(doc): improve doc generation of types using lpeg

Added a lpeg grammar for LuaCATS and use it in lua2dox.lua

1 files changed, 381 insertions, 378 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index b558a3fc8d..aadc73e95c 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -606,7 +606,7 @@ vim.highlight.on_yank({opts})                        *vim.highlight.on_yank()*
     Highlight the yanked text
 
     Parameters: ~
-      • {opts}  (table|nil) Optional parameters
+      • {opts}  (`table?`) Optional parameters
                 • higroup highlight group for yanked region (default
                   "IncSearch")
                 • timeout time in ms before highlight is cleared (default 150)
@@ -631,14 +631,14 @@ 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
+      • {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?`) Optional parameters
                    • regtype type of range (see |setreg()|, default charwise)
                    • inclusive boolean indicating whether the range is
                      end-inclusive (default false)
@@ -660,10 +660,10 @@ vim.regex({re})                                                  *vim.regex()*
     They can be controlled with flags, see |/magic| and |/ignorecase|.
 
     Parameters: ~
-      • {re}  (string)
+      • {re}  (`string`)
 
     Return: ~
-        vim.regex
+        (`vim.regex`)
 
                                                           *regex:match_line()*
 vim.regex:match_line({bufnr}, {line_idx}, {start}, {end_})
@@ -673,10 +673,10 @@ vim.regex:match_line({bufnr}, {line_idx}, {start}, {end_})
     will be relative {start}.
 
     Parameters: ~
-      • {bufnr}     (integer)
-      • {line_idx}  (integer)
-      • {start}     (integer|nil)
-      • {end_}      (integer|nil)
+      • {bufnr}     (`integer`)
+      • {line_idx}  (`integer`)
+      • {start}     (`integer?`)
+      • {end_}      (`integer?`)
 
 vim.regex:match_str({str})                                 *regex:match_str()*
     Match the string against the regex. If the string should match the regex
@@ -686,7 +686,7 @@ vim.regex:match_str({str})                                 *regex:match_str()*
     be directly used as a condition in an if-statement.
 
     Parameters: ~
-      • {str}  (string)
+      • {str}  (`string`)
 
 
 ==============================================================================
@@ -712,9 +712,9 @@ vim.diff({a}, {b}, {opts})                                        *vim.diff()*
 <
 
     Parameters: ~
-      • {a}     (string) First string to compare
-      • {b}     (string) Second string to compare
-      • {opts}  table<string,any> Optional parameters:
+      • {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:
@@ -753,7 +753,7 @@ vim.diff({a}, {b}, {opts})                                        *vim.diff()*
                   the internal diff library.
 
     Return: ~
-        string|table|nil See {opts.result_type}. `nil` if {opts.on_hunk} is
+        (`string|table?`) See {opts.result_type}. `nil` if {opts.on_hunk} is
         given.
 
 
@@ -768,7 +768,7 @@ vim.mpack.decode({str})                                   *vim.mpack.decode()*
     Decodes (or "unpacks") the msgpack-encoded {str} to a Lua object.
 
     Parameters: ~
-      • {str}  (string)
+      • {str}  (`string`)
 
 vim.mpack.encode({obj})                                   *vim.mpack.encode()*
     Encodes (or "packs") Lua object {obj} as msgpack in a Lua string.
@@ -794,8 +794,8 @@ vim.json.decode({str}, {opts})                             *vim.json.decode()*
 <
 
     Parameters: ~
-      • {str}   (string) Stringified JSON data.
-      • {opts}  table<string,any>|nil Options table with keys:
+      • {str}   (`string`) Stringified JSON data.
+      • {opts}  (`table<string,any>?`) Options table with keys:
                 • luanil: (table) Table with keys:
                   • object: (boolean) When true, converts `null` in JSON
                     objects to Lua `nil` instead of |vim.NIL|.
@@ -803,16 +803,16 @@ vim.json.decode({str}, {opts})                             *vim.json.decode()*
                     to Lua `nil` instead of |vim.NIL|.
 
     Return: ~
-        any
+        (`any`)
 
 vim.json.encode({obj})                                     *vim.json.encode()*
     Encodes (or "packs") Lua object {obj} as JSON in a Lua string.
 
     Parameters: ~
-      • {obj}  any
+      • {obj}  (`any`)
 
     Return: ~
-        (string)
+        (`string`)
 
 
 ==============================================================================
@@ -822,19 +822,19 @@ vim.base64.decode({str})                                 *vim.base64.decode()*
     Decode a Base64 encoded string.
 
     Parameters: ~
-      • {str}  (string) Base64 encoded string
+      • {str}  (`string`) Base64 encoded string
 
     Return: ~
-        (string) Decoded string
+        (`string`) Decoded string
 
 vim.base64.encode({str})                                 *vim.base64.encode()*
     Encode {str} using Base64.
 
     Parameters: ~
-      • {str}  (string) String to encode
+      • {str}  (`string`) String to encode
 
     Return: ~
-        (string) Encoded string
+        (`string`) Encoded string
 
 
 ==============================================================================
@@ -857,11 +857,11 @@ vim.spell.check({str})                                     *vim.spell.check()*
 <
 
     Parameters: ~
-      • {str}  (string)
+      • {str}  (`string`)
 
     Return: ~
-        `{[1]: string, [2]: string, [3]: string}[]` List of tuples with three
-        items:
+        (`{[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
@@ -945,13 +945,13 @@ vim.iconv({str}, {from}, {to}, {opts})                           *vim.iconv()*
     ":Man 3 iconv".
 
     Parameters: ~
-      • {str}   (string) Text to convert
-      • {from}  (number) Encoding of {str}
-      • {to}    (number) Target encoding
-      • {opts}  table<string,any>|nil
+      • {str}   (`string`) Text to convert
+      • {from}  (`number`) Encoding of {str}
+      • {to}    (`number`) Target encoding
+      • {opts}  (`table<string,any>?`)
 
     Return: ~
-        (string|nil) Converted string if conversion succeeds, `nil` otherwise.
+        (`string?`) 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,
@@ -967,10 +967,10 @@ vim.rpcnotify({channel}, {method}, {args}, {...})            *vim.rpcnotify()*
     This function also works in a fast callback |lua-loop-callbacks|.
 
     Parameters: ~
-      • {channel}  (integer)
-      • {method}   (string)
-      • {args}     any[]|nil
-      • {...}      any|nil
+      • {channel}  (`integer`)
+      • {method}   (`string`)
+      • {args}     (`any[]?`)
+      • {...}      (`any?`)
 
 vim.rpcrequest({channel}, {method}, {args}, {...})          *vim.rpcrequest()*
     Sends a request to {channel} to invoke {method} via |RPC| and blocks until
@@ -980,17 +980,17 @@ vim.rpcrequest({channel}, {method}, {args}, {...})          *vim.rpcrequest()*
     special value
 
     Parameters: ~
-      • {channel}  (integer)
-      • {method}   (string)
-      • {args}     any[]|nil
-      • {...}      any|nil
+      • {channel}  (`integer`)
+      • {method}   (`string`)
+      • {args}     (`any[]?`)
+      • {...}      (`any?`)
 
 vim.schedule({fn})                                            *vim.schedule()*
     Schedules {fn} to be invoked soon by the main event-loop. Useful to avoid
     |textlock| or other temporary restrictions.
 
     Parameters: ~
-      • {fn}  (function)
+      • {fn}  (`function`)
 
 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
@@ -1001,9 +1001,9 @@ vim.str_byteindex({str}, {index}, {use_utf16})           *vim.str_byteindex()*
     sequence.
 
     Parameters: ~
-      • {str}        (string)
-      • {index}      (number)
-      • {use_utf16}  any|nil
+      • {str}        (`string`)
+      • {index}      (`number`)
+      • {use_utf16}  (`any?`)
 
 vim.str_utf_end({str}, {index})                            *vim.str_utf_end()*
     Gets the distance (in bytes) from the last byte of the codepoint
@@ -1020,11 +1020,11 @@ vim.str_utf_end({str}, {index})                            *vim.str_utf_end()*
 <
 
     Parameters: ~
-      • {str}    (string)
-      • {index}  (number)
+      • {str}    (`string`)
+      • {index}  (`number`)
 
     Return: ~
-        (number)
+        (`number`)
 
 vim.str_utf_pos({str})                                     *vim.str_utf_pos()*
     Gets a list of the starting byte positions of each UTF-8 codepoint in the
@@ -1033,10 +1033,10 @@ vim.str_utf_pos({str})                                     *vim.str_utf_pos()*
     Embedded NUL bytes are treated as terminating the string.
 
     Parameters: ~
-      • {str}  (string)
+      • {str}  (`string`)
 
     Return: ~
-        (table)
+        (`table`)
 
 vim.str_utf_start({str}, {index})                        *vim.str_utf_start()*
     Gets the distance (in bytes) from the starting byte of the codepoint
@@ -1056,11 +1056,11 @@ vim.str_utf_start({str}, {index})                        *vim.str_utf_start()*
 <
 
     Parameters: ~
-      • {str}    (string)
-      • {index}  (number)
+      • {str}    (`string`)
+      • {index}  (`number`)
 
     Return: ~
-        (number)
+        (`number`)
 
 vim.str_utfindex({str}, {index})                          *vim.str_utfindex()*
     Convert byte index to UTF-32 and UTF-16 indices. If {index} is not
@@ -1072,23 +1072,23 @@ vim.str_utfindex({str}, {index})                          *vim.str_utfindex()*
     that sequence.
 
     Parameters: ~
-      • {str}    (string)
-      • {index}  (number|nil)
+      • {str}    (`string`)
+      • {index}  (`number?`)
 
     Return (multiple): ~
-        (integer) UTF-32 index
-        (integer) UTF-16 index
+        (`integer`) UTF-32 index
+        (`integer`) UTF-16 index
 
 vim.stricmp({a}, {b})                                          *vim.stricmp()*
     Compares strings case-insensitively.
 
     Parameters: ~
-      • {a}  (string)
-      • {b}  (string)
+      • {a}  (`string`)
+      • {b}  (`string`)
 
     Return: ~
-        0|1|-1 if strings are equal, {a} is greater than {b} or {a} is lesser
-        than {b}, respectively.
+        (`0|1|-1`) if strings are equal, {a} is greater than {b} or {a} is
+        lesser than {b}, respectively.
 
 vim.ui_attach({ns}, {options}, {callback})                   *vim.ui_attach()*
     Attach to ui events, similar to |nvim_ui_attach()| but receive events as
@@ -1126,16 +1126,16 @@ vim.ui_attach({ns}, {options}, {callback})                   *vim.ui_attach()*
 <
 
     Parameters: ~
-      • {ns}        (integer)
-      • {options}   table<string, any>
-      • {callback}  fun()
+      • {ns}        (`integer`)
+      • {options}   (`table<string, any>`)
+      • {callback}  (`fun()`)
 
 vim.ui_detach({ns})                                          *vim.ui_detach()*
     Detach a callback previously attached with |vim.ui_attach()| for the given
     namespace {ns}.
 
     Parameters: ~
-      • {ns}  (integer)
+      • {ns}  (`integer`)
 
 vim.wait({time}, {callback}, {interval}, {fast_only})             *vim.wait()*
     Wait for {time} in milliseconds until {callback} returns `true`.
@@ -1170,16 +1170,16 @@ vim.wait({time}, {callback}, {interval}, {fast_only})             *vim.wait()*
 <
 
     Parameters: ~
-      • {time}       (integer) Number of milliseconds to wait
-      • {callback}   fun():|nil boolean Optional callback. Waits until
+      • {time}       (`integer`) Number of milliseconds to wait
+      • {callback}   (`fun(): 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
+      • {interval}   (`integer?`) (Approximate) number of milliseconds to wait
+                     between polls
+      • {fast_only}  (`boolean?`) If true, only |api-fast| events will be
                      processed.
 
     Return: ~
-        boolean, nil|-1|-2
+        (`boolean, -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`
@@ -1376,7 +1376,7 @@ Option:append({value})                                      *vim.opt:append()*
 <
 
     Parameters: ~
-      • {value}  (string) Value to append
+      • {value}  (`string`) Value to append
 
 Option:get()                                                   *vim.opt:get()*
     Returns a Lua-representation of the option. Boolean, number and string
@@ -1422,7 +1422,7 @@ Option:get()                                                   *vim.opt:get()*
 <
 
     Return: ~
-        string|integer|boolean|nil value of option
+        (`string|integer|boolean?`) value of option
 
 Option:prepend({value})                                    *vim.opt:prepend()*
     Prepend a value to string-style options. See |:set^=|
@@ -1433,7 +1433,7 @@ Option:prepend({value})                                    *vim.opt:prepend()*
 <
 
     Parameters: ~
-      • {value}  (string) Value to prepend
+      • {value}  (`string`) Value to prepend
 
 Option:remove({value})                                      *vim.opt:remove()*
     Remove a value from string-style options. See |:set-=|
@@ -1444,7 +1444,7 @@ Option:remove({value})                                      *vim.opt:remove()*
 <
 
     Parameters: ~
-      • {value}  (string) Value to remove
+      • {value}  (`string`) Value to remove
 
 vim.bo                                                                *vim.bo*
     Get or set buffer-scoped |options| for the buffer with number {bufnr}.
@@ -1471,7 +1471,7 @@ vim.env                                                              *vim.env*
 <
 
     Parameters: ~
-      • {var}  (string)
+      • {var}  (`string`)
 
 vim.go                                                                *vim.go*
     Get or set global |options|. Like `:setglobal`. Invalid key is an error.
@@ -1553,12 +1553,12 @@ vim.cmd                                                            *vim.cmd()*
 <
 
     Parameters: ~
-      • {command}  string|table Command(s) to execute. If a string, executes
-                   multiple lines of Vim script at once. In this case, it is
-                   an alias to |nvim_exec2()|, where `opts.output` is set to
-                   false. Thus it works identical to |:source|. If a table,
-                   executes a single command. In this case, it is an alias to
-                   |nvim_cmd()| where `opts` is empty.
+      • {command}  (`string|table`) Command(s) to execute. If a string,
+                   executes multiple lines of Vim script at once. In this
+                   case, it is an alias to |nvim_exec2()|, where `opts.output`
+                   is set to false. Thus it works identical to |:source|. If a
+                   table, executes a single command. In this case, it is an
+                   alias to |nvim_cmd()| where `opts` is empty.
 
     See also: ~
       • |ex-cmd-index|
@@ -1570,34 +1570,34 @@ vim.defer_fn({fn}, {timeout})                                 *vim.defer_fn()*
     |vim.schedule_wrap()|ped automatically, so API functions are safe to call.
 
     Parameters: ~
-      • {fn}       (function) Callback to call once `timeout` expires
-      • {timeout}  (integer) Number of milliseconds to wait before calling
+      • {fn}       (`function`) Callback to call once `timeout` expires
+      • {timeout}  (`integer`) Number of milliseconds to wait before calling
                    `fn`
 
     Return: ~
-        (table) timer luv timer object
+        (`table`) timer luv timer object
 
                                                              *vim.deprecate()*
 vim.deprecate({name}, {alternative}, {version}, {plugin}, {backtrace})
     Shows a deprecation message to the user.
 
     Parameters: ~
-      • {name}         string Deprecated feature (function, API, etc.).
-      • {alternative}  (string|nil) Suggested alternative feature.
-      • {version}      string Version when the deprecated function will be
+      • {name}         (`string`) Deprecated feature (function, API, etc.).
+      • {alternative}  (`string?`) Suggested alternative feature.
+      • {version}      (`string`) Version when the deprecated function will be
                        removed.
-      • {plugin}       string|nil Name of the plugin that owns the deprecated
+      • {plugin}       (`string?`) Name of the plugin that owns the deprecated
                        feature. Defaults to "Nvim".
-      • {backtrace}    boolean|nil Prints backtrace. Defaults to true.
+      • {backtrace}    (`boolean?`) Prints backtrace. Defaults to true.
 
     Return: ~
-        (string|nil) Deprecated message, or nil if no message was shown.
+        (`string?`) Deprecated message, or nil if no message was shown.
 
 vim.inspect                                                    *vim.inspect()*
     Gets a human-readable representation of the given object.
 
     Return: ~
-        (string)
+        (`string`)
 
     See also: ~
       • |vim.print()|
@@ -1613,10 +1613,10 @@ vim.keycode({str})                                             *vim.keycode()*
 <
 
     Parameters: ~
-      • {str}  (string) String to be converted.
+      • {str}  (`string`) String to be converted.
 
     Return: ~
-        (string)
+        (`string`)
 
     See also: ~
       • |nvim_replace_termcodes()|
@@ -1635,9 +1635,9 @@ vim.notify({msg}, {level}, {opts})                              *vim.notify()*
     writes to |:messages|.
 
     Parameters: ~
-      • {msg}    (string) Content of the notification to show to the user.
-      • {level}  (integer|nil) One of the values from |vim.log.levels|.
-      • {opts}   (table|nil) Optional parameters. Unused by default.
+      • {msg}    (`string`) Content of the notification to show to the user.
+      • {level}  (`integer?`) One of the values from |vim.log.levels|.
+      • {opts}   (`table?`) Optional parameters. Unused by default.
 
 vim.notify_once({msg}, {level}, {opts})                    *vim.notify_once()*
     Displays a notification only one time.
@@ -1646,12 +1646,12 @@ vim.notify_once({msg}, {level}, {opts})                    *vim.notify_once()*
     display a notification.
 
     Parameters: ~
-      • {msg}    (string) Content of the notification to show to the user.
-      • {level}  (integer|nil) One of the values from |vim.log.levels|.
-      • {opts}   (table|nil) Optional parameters. Unused by default.
+      • {msg}    (`string`) Content of the notification to show to the user.
+      • {level}  (`integer?`) One of the values from |vim.log.levels|.
+      • {opts}   (`table?`) Optional parameters. Unused by default.
 
     Return: ~
-        (boolean) true if message was displayed, else false
+        (`boolean`) true if message was displayed, else false
 
 vim.on_key({fn}, {ns_id})                                       *vim.on_key()*
     Adds Lua function {fn} with namespace id {ns_id} as a listener to every,
@@ -1666,15 +1666,15 @@ vim.on_key({fn}, {ns_id})                                       *vim.on_key()*
       • {fn} will receive the keys after mappings have been evaluated
 
     Parameters: ~
-      • {fn}     fun(key: string) Function invoked on every key press.
+      • {fn}     (`fun(key: string)`) Function invoked on every key press.
                  |i_CTRL-V| Returning nil removes the callback associated with
                  namespace {ns_id}.
-      • {ns_id}  integer? Namespace ID. If nil or 0, generates and returns a
-                 new |nvim_create_namespace()| id.
+      • {ns_id}  (`integer?`) Namespace ID. If nil or 0, generates and returns
+                 a new |nvim_create_namespace()| id.
 
     Return: ~
-        (integer) Namespace id associated with {fn}. Or count of all callbacks
-        if on_key() is called without arguments.
+        (`integer`) Namespace id associated with {fn}. Or count of all
+        callbacks if on_key() is called without arguments.
 
 vim.paste({lines}, {phase})                                      *vim.paste()*
     Paste handler, invoked by |nvim_paste()| when a conforming UI (such as the
@@ -1693,9 +1693,9 @@ vim.paste({lines}, {phase})                                      *vim.paste()*
 <
 
     Parameters: ~
-      • {lines}  string[] # |readfile()|-style list of lines to paste.
+      • {lines}  (`string[]`) |readfile()|-style list of lines to paste.
                  |channel-lines|
-      • {phase}  paste_phase -1: "non-streaming" paste: the call contains all
+      • {phase}  (`-1|1|2|3`) -1: "non-streaming" paste: the call contains all
                  lines. If paste is "streamed", `phase` indicates
                  the stream state:
                  • 1: starts the paste (exactly once)
@@ -1703,10 +1703,10 @@ vim.paste({lines}, {phase})                                      *vim.paste()*
                  • 3: ends the paste (exactly once)
 
     Return: ~
-        (boolean) result false if client should cancel the paste.
+        (`boolean`) result false if client should cancel the paste.
 
     See also: ~
-      • |paste| @alias paste_phase -1 | 1 | 2 | 3
+      • |paste|
 
 vim.print({...})                                                 *vim.print()*
     "Pretty prints" the given arguments and returns them unmodified.
@@ -1716,7 +1716,7 @@ vim.print({...})                                                 *vim.print()*
 <
 
     Return: ~
-        any given arguments.
+        (`any`) given arguments.
 
     See also: ~
       • |vim.inspect()|
@@ -1732,17 +1732,17 @@ vim.region({bufnr}, {pos1}, {pos2}, {regtype}, {inclusive})
     returned as |v:maxcol| (big number).
 
     Parameters: ~
-      • {bufnr}      (integer) Buffer number, or 0 for current buffer
-      • {pos1}       integer[]|string Start of region as a (line, column)
+      • {bufnr}      (`integer`) Buffer number, or 0 for current buffer
+      • {pos1}       (`integer[]|string`) Start of region as a (line, column)
                      tuple or |getpos()|-compatible string
-      • {pos2}       integer[]|string End of region as a (line, column) tuple
-                     or |getpos()|-compatible string
-      • {regtype}    (string) |setreg()|-style selection type
-      • {inclusive}  (boolean) Controls whether the ending column is inclusive
-                     (see also 'selection').
+      • {pos2}       (`integer[]|string`) End of region as a (line, column)
+                     tuple or |getpos()|-compatible string
+      • {regtype}    (`string`) |setreg()|-style selection type
+      • {inclusive}  (`boolean`) Controls whether the ending column is
+                     inclusive (see also 'selection').
 
     Return: ~
-        (table) region Dict of the form `{linenr = {startcol,endcol}}`.
+        (`table`) region Dict of the form `{linenr = {startcol,endcol}}`.
         `endcol` is exclusive, and whole lines are returned as
         `{startcol,endcol} = {0,-1}`.
 
@@ -1759,10 +1759,10 @@ vim.schedule_wrap({fn})                                  *vim.schedule_wrap()*
 <
 
     Parameters: ~
-      • {fn}  (function)
+      • {fn}  (`function`)
 
     Return: ~
-        (function)
+        (`function`)
 
     See also: ~
       • |lua-loop-callbacks|
@@ -1792,8 +1792,8 @@ vim.system({cmd}, {opts}, {on_exit})                            *vim.system()*
     throws an error if {cmd} cannot be run.
 
     Parameters: ~
-      • {cmd}      (string[]) Command to execute
-      • {opts}     (SystemOpts|nil) Options:
+      • {cmd}      (`string[]`) Command to execute
+      • {opts}     (`vim.SystemOpts?`) Options:
                    • cwd: (string) Set the current working directory for the
                      sub-process.
                    • env: table<string,string> Set environment variables for
@@ -1823,12 +1823,13 @@ vim.system({cmd}, {opts}, {on_exit})                            *vim.system()*
                      process will still keep the parent's event loop alive
                      unless the parent process calls |uv.unref()| on the
                      child's process handle.
-      • {on_exit}  (function|nil) Called when subprocess exits. When provided,
-                   the command runs asynchronously. Receives SystemCompleted
-                   object, see return of SystemObj:wait().
+      • {on_exit}  (`fun(out: vim.SystemCompleted)?`) Called when subprocess
+                   exits. When provided, the command runs asynchronously.
+                   Receives SystemCompleted object, see return of
+                   SystemObj:wait().
 
     Return: ~
-        vim.SystemObj Object with the fields:
+        (`vim.SystemObj`) Object with the fields:
         • pid (integer) Process ID
         • wait (fun(timeout: integer|nil): SystemCompleted) Wait for the
           process to complete. Upon timeout the process is sent the KILL
@@ -1855,12 +1856,12 @@ vim.inspect_pos({bufnr}, {row}, {col}, {filter})           *vim.inspect_pos()*
     Can also be pretty-printed with `:Inspect!`.                   *:Inspect!*
 
     Parameters: ~
-      • {bufnr}   (integer|nil) defaults to the current buffer
-      • {row}     (integer|nil) row to inspect, 0-based. Defaults to the row
-                  of the current cursor
-      • {col}     (integer|nil) col to inspect, 0-based. Defaults to the col
-                  of the current cursor
-      • {filter}  (table|nil) a table with key-value pairs to filter the items
+      • {bufnr}   (`integer?`) defaults to the current buffer
+      • {row}     (`integer?`) row to inspect, 0-based. Defaults to the row of
+                  the current cursor
+      • {col}     (`integer?`) col to inspect, 0-based. Defaults to the col of
+                  the current cursor
+      • {filter}  (`table?`) a table with key-value pairs to filter the items
                   • syntax (boolean): include syntax based highlight groups
                     (defaults to true)
                   • treesitter (boolean): include treesitter based highlight
@@ -1872,7 +1873,7 @@ vim.inspect_pos({bufnr}, {row}, {col}, {filter})           *vim.inspect_pos()*
                     (defaults to true)
 
     Return: ~
-        (table) a table with the following key-value pairs. Items are in
+        (`table`) a table with the following key-value pairs. Items are in
         "traversal order":
         • treesitter: a list of treesitter captures
         • syntax: a list of syntax groups
@@ -1888,12 +1889,12 @@ vim.show_pos({bufnr}, {row}, {col}, {filter})                 *vim.show_pos()*
     Can also be shown with `:Inspect`.                              *:Inspect*
 
     Parameters: ~
-      • {bufnr}   (integer|nil) defaults to the current buffer
-      • {row}     (integer|nil) row to inspect, 0-based. Defaults to the row
-                  of the current cursor
-      • {col}     (integer|nil) col to inspect, 0-based. Defaults to the col
-                  of the current cursor
-      • {filter}  (table|nil) see |vim.inspect_pos()|
+      • {bufnr}   (`integer?`) defaults to the current buffer
+      • {row}     (`integer?`) row to inspect, 0-based. Defaults to the row of
+                  the current cursor
+      • {col}     (`integer?`) col to inspect, 0-based. Defaults to the col of
+                  the current cursor
+      • {filter}  (`table?`) see |vim.inspect_pos()|
 
 
 
@@ -1905,11 +1906,11 @@ vim.deep_equal({a}, {b})                                    *vim.deep_equal()*
     All other types are compared using the equality `==` operator.
 
     Parameters: ~
-      • {a}  any First value
-      • {b}  any Second value
+      • {a}  (`any`) First value
+      • {b}  (`any`) Second value
 
     Return: ~
-        (boolean) `true` if values are equals, else `false`
+        (`boolean`) `true` if values are equals, else `false`
 
 vim.deepcopy({orig}, {noref})                                 *vim.deepcopy()*
     Returns a deep copy of the given object. Non-table objects are copied as
@@ -1923,15 +1924,15 @@ vim.deepcopy({orig}, {noref})                                 *vim.deepcopy()*
     fields.
 
     Parameters: ~
-      • {orig}   (table) Table to copy
-      • {noref}  (boolean|nil) When `false` (default) a contained table is
-                 only copied once and all references point to this single
-                 copy. When `true` every occurrence of a table results in a
-                 new copy. This also means that a cyclic reference can cause
+      • {orig}   (`table`) Table to copy
+      • {noref}  (`boolean?`) When `false` (default) a contained table is only
+                 copied once and all references point to this single copy.
+                 When `true` every occurrence of a table results in a new
+                 copy. This also means that a cyclic reference can cause
                  `deepcopy()` to fail.
 
     Return: ~
-        (table) Table of copied keys and (nested) values.
+        (`table`) Table of copied keys and (nested) values.
 
 vim.defaulttable({createfn})                              *vim.defaulttable()*
     Creates a table whose missing keys are provided by {createfn} (like
@@ -1944,21 +1945,21 @@ vim.defaulttable({createfn})                              *vim.defaulttable()*
 <
 
     Parameters: ~
-      • {createfn}  function?(key:any):any Provides the value for a missing
+      • {createfn}  (`fun(key:any):any?`) Provides the value for a missing
                     `key`.
 
     Return: ~
-        (table) Empty table with `__index` metamethod.
+        (`table`) Empty table with `__index` metamethod.
 
 vim.endswith({s}, {suffix})                                   *vim.endswith()*
     Tests if `s` ends with `suffix`.
 
     Parameters: ~
-      • {s}       (string) String
-      • {suffix}  (string) Suffix to match
+      • {s}       (`string`) String
+      • {suffix}  (`string`) Suffix to match
 
     Return: ~
-        (boolean) `true` if `suffix` is a suffix of `s`
+        (`boolean`) `true` if `suffix` is a suffix of `s`
 
 vim.gsplit({s}, {sep}, {opts})                                  *vim.gsplit()*
     Gets an |iterator| that splits a string at each instance of a separator,
@@ -1978,15 +1979,15 @@ vim.gsplit({s}, {sep}, {opts})                                  *vim.gsplit()*
 <
 
     Parameters: ~
-      • {s}     (string) String to split
-      • {sep}   (string) Separator or pattern
-      • {opts}  (table|nil) Keyword arguments |kwargs|:
+      • {s}     (`string`) String to split
+      • {sep}   (`string`) Separator or pattern
+      • {opts}  (`table?`) Keyword arguments |kwargs|:
                 • plain: (boolean) Use `sep` literally (as in string.find).
                 • trimempty: (boolean) Discard empty segments at start and end
                   of the sequence.
 
     Return: ~
-        (function) Iterator over the split components
+        (`function`) Iterator over the split components
 
     See also: ~
       • |string.gmatch()|
@@ -1999,20 +2000,20 @@ vim.is_callable({f})                                       *vim.is_callable()*
     Returns true if object `f` can be called as a function.
 
     Parameters: ~
-      • {f}  any Any object
+      • {f}  (`any`) Any object
 
     Return: ~
-        (boolean) `true` if `f` is callable, else `false`
+        (`boolean`) `true` if `f` is callable, else `false`
 
 vim.list_contains({t}, {value})                          *vim.list_contains()*
     Checks if a list-like table (integer keys without gaps) contains `value`.
 
     Parameters: ~
-      • {t}      (table) Table to check (must be list-like, not validated)
-      • {value}  any Value to compare
+      • {t}      (`table`) Table to check (must be list-like, not validated)
+      • {value}  (`any`) Value to compare
 
     Return: ~
-        (boolean) `true` if `t` contains `value`
+        (`boolean`) `true` if `t` contains `value`
 
     See also: ~
       • |vim.tbl_contains()| for checking values in general tables
@@ -2023,13 +2024,13 @@ vim.list_extend({dst}, {src}, {start}, {finish})           *vim.list_extend()*
     NOTE: This mutates dst!
 
     Parameters: ~
-      • {dst}     (table) List which will be modified and appended to
-      • {src}     (table) List from which values will be inserted
-      • {start}   (integer|nil) Start index on src. Defaults to 1
-      • {finish}  (integer|nil) Final index on src. Defaults to `#src`
+      • {dst}     (`table`) List which will be modified and appended to
+      • {src}     (`table`) List from which values will be inserted
+      • {start}   (`integer?`) Start index on src. Defaults to 1
+      • {finish}  (`integer?`) Final index on src. Defaults to `#src`
 
     Return: ~
-        (table) dst
+        (`table`) dst
 
     See also: ~
       • |vim.tbl_extend()|
@@ -2039,21 +2040,21 @@ vim.list_slice({list}, {start}, {finish})                   *vim.list_slice()*
     (inclusive)
 
     Parameters: ~
-      • {list}    (list) Table
-      • {start}   (integer|nil) Start range of slice
-      • {finish}  (integer|nil) End range of slice
+      • {list}    (`list`) Table
+      • {start}   (`integer?`) Start range of slice
+      • {finish}  (`integer?`) End range of slice
 
     Return: ~
-        (list) Copy of table sliced from start to finish (inclusive)
+        (`list`) Copy of table sliced from start to finish (inclusive)
 
 vim.pesc({s})                                                     *vim.pesc()*
     Escapes magic chars in |lua-patterns|.
 
     Parameters: ~
-      • {s}  (string) String to escape
+      • {s}  (`string`) String to escape
 
     Return: ~
-        (string) %-escaped pattern string
+        (`string`) %-escaped pattern string
 
     See also: ~
       • https://github.com/rxi/lume
@@ -2084,10 +2085,10 @@ vim.ringbuf({size})                                            *vim.ringbuf()*
     • |Ringbuf:clear()|
 
     Parameters: ~
-      • {size}  (integer)
+      • {size}  (`integer`)
 
     Return: ~
-        (table)
+        (`table`)
 
 vim.Ringbuf:clear()                                          *Ringbuf:clear()*
     Clear all items.
@@ -2096,28 +2097,28 @@ vim.Ringbuf:peek()                                            *Ringbuf:peek()*
     Returns the first unread item without removing it
 
     Return: ~
-        any?|nil
+        (`any?`)
 
 vim.Ringbuf:pop()                                              *Ringbuf:pop()*
     Removes and returns the first unread item
 
     Return: ~
-        any?|nil
+        (`any?`)
 
 vim.Ringbuf:push({item})                                      *Ringbuf:push()*
     Adds an item, overriding the oldest item if the buffer is full.
 
     Parameters: ~
-      • {item}  any
+      • {item}  (`any`)
 
 vim.spairs({t})                                                 *vim.spairs()*
     Enumerates key-value pairs of a table, ordered by key.
 
     Parameters: ~
-      • {t}  (table) Dict-like table
+      • {t}  (`table`) Dict-like table
 
     Return: ~
-        (function) |for-in| iterator over sorted keys and their values
+        (`function`) |for-in| iterator over sorted keys and their values