Merge remote-tracking branch 'upstream/master' into mix_20240309

11 files changed, 2134 insertions, 1635 deletions

diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index 6edf2a5a96..c66b295d3a 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -20,14 +20,15 @@ function vim.api.nvim__buf_stats(buffer) end
 --- @private
 --- EXPERIMENTAL: this API may change in the future.
 ---
---- Sets info for the completion item at the given index. If the info text was
---- shown in a window, returns the window and buffer ids, or empty dict if not
---- shown.
+--- Sets info for the completion item at the given index. If the info text was shown in a window,
+--- returns the window and buffer ids, or empty dict if not shown.
 ---
 --- @param index integer Completion candidate index
 --- @param opts vim.api.keyset.complete_set Optional parameters.
----             • info: (string) info text.
---- @return table<string,any>
+--- - info: (string) info text.
+--- @return table<string,any> # Dict containing these keys:
+--- - winid: (number) floating window id
+--- - bufnr: (number) buffer id in floating window
 function vim.api.nvim__complete_set(index, opts) end
 
 --- @private
@@ -40,7 +41,7 @@ function vim.api.nvim__get_lib_dir() end
 --- @param pat any[] pattern of files to search for
 --- @param all boolean whether to return all matches or only the first
 --- @param opts vim.api.keyset.runtime is_lua: only search Lua subdirs
---- @return string[]
+--- @return string[] # list of absolute paths to the found files
 function vim.api.nvim__get_runtime(pat, all, opts) end
 
 --- @private
@@ -50,7 +51,7 @@ function vim.api.nvim__get_runtime(pat, all, opts) end
 --- in plugins.
 ---
 --- @param obj any Object to return.
---- @return any
+--- @return any # its argument.
 function vim.api.nvim__id(obj) end
 
 --- @private
@@ -60,18 +61,18 @@ function vim.api.nvim__id(obj) end
 --- in plugins.
 ---
 --- @param arr any[] Array to return.
---- @return any[]
+--- @return any[] # its argument.
 function vim.api.nvim__id_array(arr) end
 
 --- @private
---- Returns dictionary given as argument.
+--- Returns dict given as argument.
 ---
 --- This API function is used for testing. One should not rely on its presence
 --- in plugins.
 ---
---- @param dct table<string,any> Dictionary to return.
---- @return table<string,any>
-function vim.api.nvim__id_dictionary(dct) end
+--- @param dct table<string,any> Dict to return.
+--- @return table<string,any> # its argument.
+function vim.api.nvim__id_dict(dct) end
 
 --- @private
 --- Returns floating-point value given as argument.
@@ -80,13 +81,11 @@ function vim.api.nvim__id_dictionary(dct) end
 --- in plugins.
 ---
 --- @param flt number Value to return.
---- @return number
+--- @return number # its argument.
 function vim.api.nvim__id_float(flt) end
 
 --- @private
---- NB: if your UI doesn't use hlstate, this will not return hlstate first
---- time.
----
+--- NB: if your UI doesn't use hlstate, this will not return hlstate first time.
 --- @param grid integer
 --- @param row integer
 --- @param col integer
@@ -94,35 +93,55 @@ function vim.api.nvim__id_float(flt) end
 function vim.api.nvim__inspect_cell(grid, row, col) end
 
 --- @private
---- For testing. The condition in schar_cache_clear_if_full is hard to reach,
---- so this function can be used to force a cache clear in a test.
----
+--- For testing. The condition in schar_cache_clear_if_full is hard to
+--- reach, so this function can be used to force a cache clear in a test.
 function vim.api.nvim__invalidate_glyph_cache() end
 
 --- @private
+--- EXPERIMENTAL: this API will change in the future.
+---
+--- Get the properties for namespace
+---
+--- @param ns_id integer Namespace
+--- @return vim.api.keyset.ns_opts # Map defining the namespace properties, see |nvim__ns_set()|
+function vim.api.nvim__ns_get(ns_id) end
+
+--- @private
+--- EXPERIMENTAL: this API will change in the future.
+---
+--- Set some properties for namespace
+---
+--- @param ns_id integer Namespace
+--- @param opts vim.api.keyset.ns_opts Optional parameters to set:
+--- - wins: a list of windows to be scoped in
+function vim.api.nvim__ns_set(ns_id, opts) end
+
+--- @private
 --- EXPERIMENTAL: this API may change in the future.
 ---
 --- Instruct Nvim to redraw various components.
 ---
+---
+--- @see `:help :redraw`
 --- @param opts vim.api.keyset.redraw Optional parameters.
----             • win: Target a specific `window-ID` as described below.
----             • buf: Target a specific buffer number as described below.
----             • flush: Update the screen with pending updates.
----             • valid: When present mark `win`, `buf`, or all windows for
----               redraw. When `true`, only redraw changed lines (useful for
----               decoration providers). When `false`, forcefully redraw.
----             • range: Redraw a range in `buf`, the buffer in `win` or the
----               current buffer (useful for decoration providers). Expects a
----               tuple `[first, last]` with the first and last line number of
----               the range, 0-based end-exclusive `api-indexing`.
----             • cursor: Immediately update cursor position on the screen in
----               `win` or the current window.
----             • statuscolumn: Redraw the 'statuscolumn' in `buf`, `win` or
----               all windows.
----             • statusline: Redraw the 'statusline' in `buf`, `win` or all
----               windows.
----             • winbar: Redraw the 'winbar' in `buf`, `win` or all windows.
----             • tabline: Redraw the 'tabline'.
+--- - win: Target a specific `window-ID` as described below.
+--- - buf: Target a specific buffer number as described below.
+--- - flush: Update the screen with pending updates.
+--- - valid: When present mark `win`, `buf`, or all windows for
+---   redraw. When `true`, only redraw changed lines (useful for
+---   decoration providers). When `false`, forcefully redraw.
+--- - range: Redraw a range in `buf`, the buffer in `win` or the
+---   current buffer (useful for decoration providers). Expects a
+---   tuple `[first, last]` with the first and last line number
+---   of the range, 0-based end-exclusive `api-indexing`.
+--- - cursor: Immediately update cursor position on the screen in
+---   `win` or the current window.
+--- - statuscolumn: Redraw the 'statuscolumn' in `buf`, `win` or
+---   all windows.
+--- - statusline: Redraw the 'statusline' in `buf`, `win` or all
+---   windows.
+--- - winbar: Redraw the 'winbar' in `buf`, `win` or all windows.
+--- - tabline: Redraw the 'tabline'.
 function vim.api.nvim__redraw(opts) end
 
 --- @private
@@ -136,7 +155,7 @@ function vim.api.nvim__screenshot(path) end
 --- @private
 --- Gets internal stats.
 ---
---- @return table<string,any>
+--- @return table<string,any> # Map of various internal stats.
 function vim.api.nvim__stats() end
 
 --- @private
@@ -144,50 +163,20 @@ function vim.api.nvim__stats() end
 --- @return any
 function vim.api.nvim__unpack(str) end
 
---- @private
---- EXPERIMENTAL: this API will change in the future.
----
---- Scopes a namespace to the a window, so extmarks in the namespace will be
---- active only in the given window.
----
---- @param window integer Window handle, or 0 for current window
---- @param ns_id integer Namespace
---- @return boolean
-function vim.api.nvim__win_add_ns(window, ns_id) end
-
---- @private
---- EXPERIMENTAL: this API will change in the future.
----
---- Unscopes a namespace (un-binds it from the given scope).
----
---- @param window integer Window handle, or 0 for current window
---- @param ns_id integer the namespace to remove
---- @return boolean
-function vim.api.nvim__win_del_ns(window, ns_id) end
-
---- @private
---- EXPERIMENTAL: this API will change in the future.
----
---- Gets the namespace scopes for a given window.
----
---- @param window integer Window handle, or 0 for current window
---- @return integer[]
-function vim.api.nvim__win_get_ns(window) end
-
 --- Adds a highlight to buffer.
 ---
---- Useful for plugins that dynamically generate highlights to a buffer (like
---- a semantic highlighter or linter). The function adds a single highlight to
---- a buffer. Unlike `matchaddpos()` highlights follow changes to line
---- numbering (as lines are inserted/removed above the highlighted line), like
---- signs and marks do.
+--- Useful for plugins that dynamically generate highlights to a buffer
+--- (like a semantic highlighter or linter). The function adds a single
+--- highlight to a buffer. Unlike `matchaddpos()` highlights follow changes to
+--- line numbering (as lines are inserted/removed above the highlighted line),
+--- like signs and marks do.
 ---
 --- Namespaces are used for batch deletion/updating of a set of highlights. To
---- create a namespace, use `nvim_create_namespace()` which returns a
---- namespace id. Pass it in to this function as `ns_id` to add highlights to
---- the namespace. All highlights in the same namespace can then be cleared
---- with single call to `nvim_buf_clear_namespace()`. If the highlight never
---- will be deleted by an API call, pass `ns_id = -1`.
+--- create a namespace, use `nvim_create_namespace()` which returns a namespace
+--- id. Pass it in to this function as `ns_id` to add highlights to the
+--- namespace. All highlights in the same namespace can then be cleared with
+--- single call to `nvim_buf_clear_namespace()`. If the highlight never will be
+--- deleted by an API call, pass `ns_id = -1`.
 ---
 --- As a shorthand, `ns_id = 0` can be used to create a new namespace for the
 --- highlight, the allocated id is then returned. If `hl_group` is the empty
@@ -200,98 +189,100 @@ function vim.api.nvim__win_get_ns(window) end
 --- @param hl_group string Name of the highlight group to use
 --- @param line integer Line to highlight (zero-indexed)
 --- @param col_start integer Start of (byte-indexed) column range to highlight
---- @param col_end integer End of (byte-indexed) column range to highlight, or -1 to
----                highlight to end of line
---- @return integer
+--- @param col_end integer End of (byte-indexed) column range to highlight,
+--- or -1 to highlight to end of line
+--- @return integer # The ns_id that was used
 function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start, col_end) end
 
 --- Activates buffer-update events on a channel, or as Lua callbacks.
 ---
---- Example (Lua): capture buffer updates in a global `events` variable (use
---- "vim.print(events)" to see its contents):
+--- Example (Lua): capture buffer updates in a global `events` variable
+--- (use "vim.print(events)" to see its contents):
 ---
 --- ```lua
----     events = {}
----     vim.api.nvim_buf_attach(0, false, {
----       on_lines = function(...)
----         table.insert(events, {...})
----       end,
----     })
+--- events = {}
+--- vim.api.nvim_buf_attach(0, false, {
+---   on_lines = function(...)
+---     table.insert(events, {...})
+---   end,
+--- })
 --- ```
 ---
 ---
+--- @see vim.api.nvim_buf_detach
+--- @see `:help api-buffer-updates-lua`
 --- @param buffer integer Buffer handle, or 0 for current buffer
 --- @param send_buffer boolean True if the initial notification should contain the
----                    whole buffer: first notification will be
----                    `nvim_buf_lines_event`. Else the first notification
----                    will be `nvim_buf_changedtick_event`. Not for Lua
----                    callbacks.
+--- whole buffer: first notification will be `nvim_buf_lines_event`.
+--- Else the first notification will be `nvim_buf_changedtick_event`.
+--- Not for Lua callbacks.
 --- @param opts vim.api.keyset.buf_attach Optional parameters.
----             • on_lines: Lua callback invoked on change. Return a truthy
----               value (not `false` or `nil`) to detach. Args:
----               • the string "lines"
----               • buffer handle
----               • b:changedtick
----               • first line that changed (zero-indexed)
----               • last line that was changed
----               • last line in the updated range
----               • byte count of previous contents
----               • deleted_codepoints (if `utf_sizes` is true)
----               • deleted_codeunits (if `utf_sizes` is true)
----             • on_bytes: Lua callback invoked on change. This callback
----               receives more granular information about the change compared
----               to on_lines. Return a truthy value (not `false` or `nil`) to
----               detach. Args:
----               • the string "bytes"
----               • buffer handle
----               • b:changedtick
----               • start row of the changed text (zero-indexed)
----               • start column of the changed text
----               • byte offset of the changed text (from the start of the
----                 buffer)
----               • old end row of the changed text (offset from start row)
----               • old end column of the changed text (if old end row = 0,
----                 offset from start column)
----               • old end byte length of the changed text
----               • new end row of the changed text (offset from start row)
----               • new end column of the changed text (if new end row = 0,
----                 offset from start column)
----               • new end byte length of the changed text
----             • on_changedtick: Lua callback invoked on changedtick
----               increment without text change. Args:
----               • the string "changedtick"
----               • buffer handle
----               • b:changedtick
----             • on_detach: Lua callback invoked on detach. Args:
----               • the string "detach"
----               • buffer handle
----             • on_reload: Lua callback invoked on reload. The entire buffer
----               content should be considered changed. Args:
----               • the string "reload"
----               • buffer handle
----             • utf_sizes: include UTF-32 and UTF-16 size of the replaced
----               region, as args to `on_lines`.
----             • preview: also attach to command preview (i.e. 'inccommand')
----               events.
---- @return boolean
+--- - on_lines: Lua callback invoked on change.
+---   Return a truthy value (not `false` or `nil`) to detach. Args:
+---   - the string "lines"
+---   - buffer handle
+---   - b:changedtick
+---   - first line that changed (zero-indexed)
+---   - last line that was changed
+---   - last line in the updated range
+---   - byte count of previous contents
+---   - deleted_codepoints (if `utf_sizes` is true)
+---   - deleted_codeunits (if `utf_sizes` is true)
+--- - on_bytes: Lua callback invoked on change.
+---   This callback receives more granular information about the
+---   change compared to on_lines.
+---   Return a truthy value (not `false` or `nil`) to detach. Args:
+---   - the string "bytes"
+---   - buffer handle
+---   - b:changedtick
+---   - start row of the changed text (zero-indexed)
+---   - start column of the changed text
+---   - byte offset of the changed text (from the start of
+---       the buffer)
+---   - old end row of the changed text (offset from start row)
+---   - old end column of the changed text
+---     (if old end row = 0, offset from start column)
+---   - old end byte length of the changed text
+---   - new end row of the changed text (offset from start row)
+---   - new end column of the changed text
+---     (if new end row = 0, offset from start column)
+---   - new end byte length of the changed text
+--- - on_changedtick: Lua callback invoked on changedtick
+---   increment without text change. Args:
+---   - the string "changedtick"
+---   - buffer handle
+---   - b:changedtick
+--- - on_detach: Lua callback invoked on detach. Args:
+---   - the string "detach"
+---   - buffer handle
+--- - on_reload: Lua callback invoked on reload. The entire buffer
+---              content should be considered changed. Args:
+---   - the string "reload"
+---   - buffer handle
+--- - utf_sizes: include UTF-32 and UTF-16 size of the replaced
+---   region, as args to `on_lines`.
+--- - preview: also attach to command preview (i.e. 'inccommand')
+---   events.
+--- @return boolean # False if attach failed (invalid parameter, or buffer isn't loaded);
+--- otherwise True. TODO: LUA_API_NO_EVAL
 function vim.api.nvim_buf_attach(buffer, send_buffer, opts) end
 
---- call a function with buffer as temporary current buffer
+--- Call a function with buffer as temporary current buffer.
 ---
---- This temporarily switches current buffer to "buffer". If the current
---- window already shows "buffer", the window is not switched If a window
---- inside the current tabpage (including a float) already shows the buffer
---- One of these windows will be set as current window temporarily. Otherwise
---- a temporary scratch window (called the "autocmd window" for historical
---- reasons) will be used.
+--- This temporarily switches current buffer to "buffer".
+--- If the current window already shows "buffer", the window is not switched.
+--- If a window inside the current tabpage (including a float) already shows the
+--- buffer, then one of these windows will be set as current window temporarily.
+--- Otherwise a temporary scratch window (called the "autocmd window" for
+--- historical reasons) will be used.
 ---
 --- This is useful e.g. to call Vimscript functions that only work with the
 --- current buffer/window currently, like `termopen()`.
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
 --- @param fun function Function to call inside the buffer (currently Lua callable
----            only)
---- @return any
+--- only)
+--- @return any # Return value of function.
 function vim.api.nvim_buf_call(buffer, fun) end
 
 --- @deprecated
@@ -301,21 +292,22 @@ function vim.api.nvim_buf_call(buffer, fun) end
 --- @param line_end integer
 function vim.api.nvim_buf_clear_highlight(buffer, ns_id, line_start, line_end) end
 
---- Clears `namespace`d objects (highlights, `extmarks`, virtual text) from a
---- region.
+--- Clears `namespace`d objects (highlights, `extmarks`, virtual text) from
+--- a region.
 ---
---- Lines are 0-indexed. `api-indexing` To clear the namespace in the entire
+--- Lines are 0-indexed. `api-indexing`  To clear the namespace in the entire
 --- buffer, specify line_start=0 and line_end=-1.
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
 --- @param ns_id integer Namespace to clear, or -1 to clear all namespaces.
 --- @param line_start integer Start of range of lines to clear
 --- @param line_end integer End of range of lines to clear (exclusive) or -1 to clear
----                 to end of buffer.
+--- to end of buffer.
 function vim.api.nvim_buf_clear_namespace(buffer, ns_id, line_start, line_end) end
 
 --- Creates a buffer-local command `user-commands`.
 ---
+--- @see vim.api.nvim_create_user_command
 --- @param buffer integer Buffer handle, or 0 for current buffer.
 --- @param name string
 --- @param command any
@@ -327,11 +319,13 @@ function vim.api.nvim_buf_create_user_command(buffer, name, command, opts) end
 --- @param buffer integer Buffer handle, or 0 for current buffer
 --- @param ns_id integer Namespace id from `nvim_create_namespace()`
 --- @param id integer Extmark id
---- @return boolean
+--- @return boolean # true if the extmark was found, else false
 function vim.api.nvim_buf_del_extmark(buffer, ns_id, id) end
 
 --- Unmaps a buffer-local `mapping` for the given mode.
 ---
+---
+--- @see vim.api.nvim_del_keymap
 --- @param buffer integer Buffer handle, or 0 for current buffer
 --- @param mode string
 --- @param lhs string
@@ -339,9 +333,15 @@ function vim.api.nvim_buf_del_keymap(buffer, mode, lhs) end
 
 --- Deletes a named mark in the buffer. See `mark-motions`.
 ---
+--- Note:
+--- only deletes marks set in the buffer, if the mark is not set
+--- in the buffer it will return false.
+---
+--- @see vim.api.nvim_buf_set_mark
+--- @see vim.api.nvim_del_mark
 --- @param buffer integer Buffer to set the mark on
 --- @param name string Mark name
---- @return boolean
+--- @return boolean # true if the mark was deleted, else false.
 function vim.api.nvim_buf_del_mark(buffer, name) end
 
 --- Delete a buffer-local user-defined command.
@@ -363,21 +363,21 @@ function vim.api.nvim_buf_del_var(buffer, name) end
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
 --- @param opts vim.api.keyset.buf_delete Optional parameters. Keys:
----             • force: Force deletion and ignore unsaved changes.
----             • unload: Unloaded only, do not delete. See `:bunload`
+--- - force:  Force deletion and ignore unsaved changes.
+--- - unload: Unloaded only, do not delete. See `:bunload`
 function vim.api.nvim_buf_delete(buffer, opts) end
 
 --- Gets a changed tick of a buffer
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
---- @return integer
+--- @return integer # `b:changedtick` value.
 function vim.api.nvim_buf_get_changedtick(buffer) end
 
 --- Gets a map of buffer-local `user-commands`.
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
 --- @param opts vim.api.keyset.get_commands Optional parameters. Currently not used.
---- @return table<string,any>
+--- @return table<string,any> # Map of maps describing commands.
 function vim.api.nvim_buf_get_commands(buffer, opts) end
 
 --- Gets the position (0-indexed) of an `extmark`.
@@ -386,10 +386,10 @@ function vim.api.nvim_buf_get_commands(buffer, opts) end
 --- @param ns_id integer Namespace id from `nvim_create_namespace()`
 --- @param id integer Extmark id
 --- @param opts vim.api.keyset.get_extmark Optional parameters. Keys:
----             • details: Whether to include the details dict
----             • hl_name: Whether to include highlight group name instead of
----               id, true if omitted
---- @return vim.api.keyset.get_extmark_item
+--- - details: Whether to include the details dict
+--- - hl_name: Whether to include highlight group name instead of id, true if omitted
+--- @return vim.api.keyset.get_extmark_item_by_id # 0-indexed (row, col) tuple or empty list () if extmark id was
+--- absent
 function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end
 
 --- Gets `extmarks` in "traversal order" from a `charwise` region defined by
@@ -400,70 +400,67 @@ function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end
 --- respectively, thus the following are equivalent:
 ---
 --- ```lua
----     vim.api.nvim_buf_get_extmarks(0, my_ns, 0, -1, {})
----     vim.api.nvim_buf_get_extmarks(0, my_ns, {0,0}, {-1,-1}, {})
+--- vim.api.nvim_buf_get_extmarks(0, my_ns, 0, -1, {})
+--- vim.api.nvim_buf_get_extmarks(0, my_ns, {0,0}, {-1,-1}, {})
 --- ```
 ---
---- If `end` is less than `start`, traversal works backwards. (Useful with
---- `limit`, to get the first marks prior to a given position.)
+--- If `end` is less than `start`, traversal works backwards. (Useful
+--- with `limit`, to get the first marks prior to a given position.)
 ---
 --- Note: when using extmark ranges (marks with a end_row/end_col position)
---- the `overlap` option might be useful. Otherwise only the start position of
---- an extmark will be considered.
+--- the `overlap` option might be useful. Otherwise only the start position
+--- of an extmark will be considered.
 ---
---- Note: legacy signs placed through the `:sign` commands are implemented as
---- extmarks and will show up here. Their details array will contain a
+--- Note: legacy signs placed through the `:sign` commands are implemented
+--- as extmarks and will show up here. Their details array will contain a
 --- `sign_name` field.
 ---
 --- Example:
 ---
 --- ```lua
----     local api = vim.api
----     local pos = api.nvim_win_get_cursor(0)
----     local ns  = api.nvim_create_namespace('my-plugin')
----     -- Create new extmark at line 1, column 1.
----     local m1  = api.nvim_buf_set_extmark(0, ns, 0, 0, {})
----     -- Create new extmark at line 3, column 1.
----     local m2  = api.nvim_buf_set_extmark(0, ns, 2, 0, {})
----     -- Get extmarks only from line 3.
----     local ms  = api.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {})
----     -- Get all marks in this buffer + namespace.
----     local all = api.nvim_buf_get_extmarks(0, ns, 0, -1, {})
----     vim.print(ms)
+--- local api = vim.api
+--- local pos = api.nvim_win_get_cursor(0)
+--- local ns  = api.nvim_create_namespace('my-plugin')
+--- -- Create new extmark at line 1, column 1.
+--- local m1  = api.nvim_buf_set_extmark(0, ns, 0, 0, {})
+--- -- Create new extmark at line 3, column 1.
+--- local m2  = api.nvim_buf_set_extmark(0, ns, 2, 0, {})
+--- -- Get extmarks only from line 3.
+--- local ms  = api.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {})
+--- -- Get all marks in this buffer + namespace.
+--- local all = api.nvim_buf_get_extmarks(0, ns, 0, -1, {})
+--- vim.print(ms)
 --- ```
 ---
----
 --- @param buffer integer Buffer handle, or 0 for current buffer
---- @param ns_id integer Namespace id from `nvim_create_namespace()` or -1 for all
----              namespaces
+--- @param ns_id integer Namespace id from `nvim_create_namespace()` or -1 for all namespaces
 --- @param start any Start of range: a 0-indexed (row, col) or valid extmark id
----              (whose position defines the bound). `api-indexing`
+--- (whose position defines the bound). `api-indexing`
 --- @param end_ any End of range (inclusive): a 0-indexed (row, col) or valid
----             extmark id (whose position defines the bound). `api-indexing`
+--- extmark id (whose position defines the bound). `api-indexing`
 --- @param opts vim.api.keyset.get_extmarks Optional parameters. Keys:
----             • limit: Maximum number of marks to return
----             • details: Whether to include the details dict
----             • hl_name: Whether to include highlight group name instead of
----               id, true if omitted
----             • overlap: Also include marks which overlap the range, even if
----               their start position is less than `start`
----             • type: Filter marks by type: "highlight", "sign", "virt_text"
----               and "virt_lines"
---- @return vim.api.keyset.get_extmark_item[]
+--- - limit:  Maximum number of marks to return
+--- - details: Whether to include the details dict
+--- - hl_name: Whether to include highlight group name instead of id, true if omitted
+--- - overlap: Also include marks which overlap the range, even if
+---            their start position is less than `start`
+--- - type: Filter marks by type: "highlight", "sign", "virt_text" and "virt_lines"
+--- @return vim.api.keyset.get_extmark_item[] # List of `[extmark_id, row, col]` tuples in "traversal order".
 function vim.api.nvim_buf_get_extmarks(buffer, ns_id, start, end_, opts) end
 
 --- Gets a list of buffer-local `mapping` definitions.
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
 --- @param mode string Mode short-name ("n", "i", "v", ...)
---- @return vim.api.keyset.keymap[]
+--- @return vim.api.keyset.keymap[] # Array of |maparg()|-like dictionaries describing mappings.
+--- The "buffer" key holds the associated buffer handle.
 function vim.api.nvim_buf_get_keymap(buffer, mode) end
 
 --- Gets a line-range from the buffer.
 ---
---- Indexing is zero-based, end-exclusive. Negative indices are interpreted as
---- length+1+index: -1 refers to the index past the end. So to get the last
---- element use start=-2 and end=-1.
+--- Indexing is zero-based, end-exclusive. Negative indices are interpreted
+--- as length+1+index: -1 refers to the index past the end. So to get the
+--- last element use start=-2 and end=-1.
 ---
 --- Out-of-bounds indices are clamped to the nearest valid value, unless
 --- `strict_indexing` is set.
@@ -472,24 +469,27 @@ function vim.api.nvim_buf_get_keymap(buffer, mode) end
 --- @param start integer First line index
 --- @param end_ integer Last line index, exclusive
 --- @param strict_indexing boolean Whether out-of-bounds should be an error.
---- @return string[]
+--- @return string[] # Array of lines, or empty array for unloaded buffer.
 function vim.api.nvim_buf_get_lines(buffer, start, end_, strict_indexing) end
 
 --- Returns a `(row,col)` tuple representing the position of the named mark.
---- "End of line" column position is returned as `v:maxcol` (big number). See
---- `mark-motions`.
+--- "End of line" column position is returned as `v:maxcol` (big number).
+--- See `mark-motions`.
 ---
 --- Marks are (1,0)-indexed. `api-indexing`
 ---
+--- @see vim.api.nvim_buf_set_mark
+--- @see vim.api.nvim_buf_del_mark
 --- @param buffer integer Buffer handle, or 0 for current buffer
 --- @param name string Mark name
---- @return integer[]
+--- @return integer[] # (row, col) tuple, (0, 0) if the mark is not set, or is an
+--- uppercase/file mark set in another buffer.
 function vim.api.nvim_buf_get_mark(buffer, name) end
 
 --- Gets the full file name for the buffer
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
---- @return string
+--- @return string # Buffer name
 function vim.api.nvim_buf_get_name(buffer) end
 
 --- @deprecated
@@ -504,12 +504,12 @@ function vim.api.nvim_buf_get_number(buffer) end
 --- last line gives the total byte-count of the buffer. A final EOL byte is
 --- counted if it would be written, see 'eol'.
 ---
---- Unlike `line2byte()`, throws error for out-of-bounds indexing. Returns -1
---- for unloaded buffer.
+--- Unlike `line2byte()`, throws error for out-of-bounds indexing.
+--- Returns -1 for unloaded buffer.
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
 --- @param index integer Line index
---- @return integer
+--- @return integer # Integer byte offset, or -1 for unloaded buffer.
 function vim.api.nvim_buf_get_offset(buffer, index) end
 
 --- @deprecated
@@ -534,49 +534,54 @@ function vim.api.nvim_buf_get_option(buffer, name) end
 --- @param end_row integer Last line index, inclusive
 --- @param end_col integer Ending column (byte offset) on last line, exclusive
 --- @param opts vim.api.keyset.empty Optional parameters. Currently unused.
---- @return string[]
+--- @return string[] # Array of lines, or empty array for unloaded buffer.
 function vim.api.nvim_buf_get_text(buffer, start_row, start_col, end_row, end_col, opts) end
 
 --- Gets a buffer-scoped (b:) variable.
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
 --- @param name string Variable name
---- @return any
+--- @return any # Variable value
 function vim.api.nvim_buf_get_var(buffer, name) end
 
 --- Checks if a buffer is valid and loaded. See `api-buffer` for more info
 --- about unloaded buffers.
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
---- @return boolean
+--- @return boolean # true if the buffer is valid and loaded, false otherwise.
 function vim.api.nvim_buf_is_loaded(buffer) end
 
 --- Checks if a buffer is valid.
 ---
+--- Note:
+--- Even if a buffer is valid it may have been unloaded. See |api-buffer|
+--- for more info about unloaded buffers.
+---
+---
 --- @param buffer integer Buffer handle, or 0 for current buffer
---- @return boolean
+--- @return boolean # true if the buffer is valid, false otherwise.
 function vim.api.nvim_buf_is_valid(buffer) end
 
 --- Returns the number of lines in the given buffer.
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
---- @return integer
+--- @return integer # Line count, or 0 for unloaded buffer. |api-buffer|
 function vim.api.nvim_buf_line_count(buffer) end
 
 --- Creates or updates an `extmark`.
 ---
---- By default a new extmark is created when no id is passed in, but it is
---- also possible to create a new mark by passing in a previously unused id or
---- move an existing mark by passing in its id. The caller must then keep
---- track of existing and unused ids itself. (Useful over RPC, to avoid
---- waiting for the return value.)
+--- By default a new extmark is created when no id is passed in, but it is also
+--- possible to create a new mark by passing in a previously unused id or move
+--- an existing mark by passing in its id. The caller must then keep track of
+--- existing and unused ids itself. (Useful over RPC, to avoid waiting for the
+--- return value.)
 ---
---- Using the optional arguments, it is possible to use this to highlight a
---- range of text, and also to associate virtual text to the mark.
+--- Using the optional arguments, it is possible to use this to highlight
+--- a range of text, and also to associate virtual text to the mark.
 ---
---- If present, the position defined by `end_col` and `end_row` should be
---- after the start position in order for the extmark to cover a range. An
---- earlier end position is not an error, but then it behaves like an empty
+--- If present, the position defined by `end_col` and `end_row` should be after
+--- the start position in order for the extmark to cover a range.
+--- An earlier end position is not an error, but then it behaves like an empty
 --- range (no highlighting).
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
@@ -584,115 +589,122 @@ function vim.api.nvim_buf_line_count(buffer) end
 --- @param line integer Line where to place the mark, 0-based. `api-indexing`
 --- @param col integer Column where to place the mark, 0-based. `api-indexing`
 --- @param opts vim.api.keyset.set_extmark Optional parameters.
----             • id : id of the extmark to edit.
----             • end_row : ending line of the mark, 0-based inclusive.
----             • end_col : ending col of the mark, 0-based exclusive.
----             • hl_group : name of the highlight group used to highlight
----               this mark.
----             • hl_eol : when true, for a multiline highlight covering the
----               EOL of a line, continue the highlight for the rest of the
----               screen line (just like for diff and cursorline highlight).
----             • virt_text : virtual text to link to this mark. A list of
----               `[text, highlight]` tuples, each representing a text chunk
----               with specified highlight. `highlight` element can either be
----               a single highlight group, or an array of multiple highlight
----               groups that will be stacked (highest priority last). A
----               highlight group can be supplied either as a string or as an
----               integer, the latter which can be obtained using
----               `nvim_get_hl_id_by_name()`.
----             • virt_text_pos : position of virtual text. Possible values:
----               • "eol": right after eol character (default).
----               • "overlay": display over the specified column, without
----                 shifting the underlying text.
----               • "right_align": display right aligned in the window.
----               • "inline": display at the specified column, and shift the
----                 buffer text to the right as needed.
----             • virt_text_win_col : position the virtual text at a fixed
----               window column (starting from the first text column of the
----               screen line) instead of "virt_text_pos".
----             • virt_text_hide : hide the virtual text when the background
----               text is selected or hidden because of scrolling with
----               'nowrap' or 'smoothscroll'. Currently only affects "overlay"
----               virt_text.
----             • virt_text_repeat_linebreak : repeat the virtual text on
----               wrapped lines.
----             • hl_mode : control how highlights are combined with the
----               highlights of the text. Currently only affects virt_text
----               highlights, but might affect `hl_group` in later versions.
----               • "replace": only show the virt_text color. This is the
----                 default.
----               • "combine": combine with background text color.
----               • "blend": blend with background text color. Not supported
----                 for "inline" virt_text.
----             • virt_lines : virtual lines to add next to this mark This
----               should be an array over lines, where each line in turn is an
----               array over `[text, highlight]` tuples. In general, buffer
----               and window options do not affect the display of the text. In
----               particular 'wrap' and 'linebreak' options do not take
----               effect, so the number of extra screen lines will always
----               match the size of the array. However the 'tabstop' buffer
----               option is still used for hard tabs. By default lines are
----               placed below the buffer line containing the mark.
----             • virt_lines_above: place virtual lines above instead.
----             • virt_lines_leftcol: Place extmarks in the leftmost column of
----               the window, bypassing sign and number columns.
----             • ephemeral : for use with `nvim_set_decoration_provider()`
----               callbacks. The mark will only be used for the current redraw
----               cycle, and not be permantently stored in the buffer.
----             • right_gravity : boolean that indicates the direction the
----               extmark will be shifted in when new text is inserted (true
----               for right, false for left). Defaults to true.
----             • end_right_gravity : boolean that indicates the direction the
----               extmark end position (if it exists) will be shifted in when
----               new text is inserted (true for right, false for left).
----               Defaults to false.
----             • undo_restore : Restore the exact position of the mark if
----               text around the mark was deleted and then restored by undo.
----               Defaults to true.
----             • invalidate : boolean that indicates whether to hide the
----               extmark if the entirety of its range is deleted. For hidden
----               marks, an "invalid" key is added to the "details" array of
----               `nvim_buf_get_extmarks()` and family. If "undo_restore" is
----               false, the extmark is deleted instead.
----             • priority: a priority value for the highlight group, sign
----               attribute or virtual text. For virtual text, item with
----               highest priority is drawn last. For example treesitter
----               highlighting uses a value of 100.
----             • strict: boolean that indicates extmark should not be placed
----               if the line or column value is past the end of the buffer or
----               end of the line respectively. Defaults to true.
----             • sign_text: string of length 1-2 used to display in the sign
----               column.
----             • sign_hl_group: name of the highlight group used to highlight
----               the sign column text.
----             • number_hl_group: name of the highlight group used to
----               highlight the number column.
----             • line_hl_group: name of the highlight group used to highlight
----               the whole line.
----             • cursorline_hl_group: name of the highlight group used to
----               highlight the sign column text when the cursor is on the
----               same line as the mark and 'cursorline' is enabled.
----             • conceal: string which should be either empty or a single
----               character. Enable concealing similar to `:syn-conceal`. When
----               a character is supplied it is used as `:syn-cchar`.
----               "hl_group" is used as highlight for the cchar if provided,
----               otherwise it defaults to `hl-Conceal`.
----             • spell: boolean indicating that spell checking should be
----               performed within this extmark
----             • ui_watched: boolean that indicates the mark should be drawn
----               by a UI. When set, the UI will receive win_extmark events.
----               Note: the mark is positioned by virt_text attributes. Can be
----               used together with virt_text.
----             • url: A URL to associate with this extmark. In the TUI, the
----               OSC 8 control sequence is used to generate a clickable
----               hyperlink to this URL.
----             • scoped: boolean (EXPERIMENTAL) enables "scoping" for the
----               extmark. See `nvim__win_add_ns()`
---- @return integer
+--- - id : id of the extmark to edit.
+--- - end_row : ending line of the mark, 0-based inclusive.
+--- - end_col : ending col of the mark, 0-based exclusive.
+--- - hl_group : name of the highlight group used to highlight
+---     this mark.
+--- - hl_eol : when true, for a multiline highlight covering the
+---            EOL of a line, continue the highlight for the rest
+---            of the screen line (just like for diff and
+---            cursorline highlight).
+--- - virt_text : virtual text to link to this mark.
+---     A list of `[text, highlight]` tuples, each representing a
+---     text chunk with specified highlight. `highlight` element
+---     can either be a single highlight group, or an array of
+---     multiple highlight groups that will be stacked
+---     (highest priority last). A highlight group can be supplied
+---     either as a string or as an integer, the latter which
+---     can be obtained using `nvim_get_hl_id_by_name()`.
+--- - virt_text_pos : position of virtual text. Possible values:
+---   - "eol": right after eol character (default).
+---   - "overlay": display over the specified column, without
+---                shifting the underlying text.
+---   - "right_align": display right aligned in the window.
+---   - "inline": display at the specified column, and
+---               shift the buffer text to the right as needed.
+--- - virt_text_win_col : position the virtual text at a fixed
+---                       window column (starting from the first
+---                       text column of the screen line) instead
+---                       of "virt_text_pos".
+--- - virt_text_hide : hide the virtual text when the background
+---                    text is selected or hidden because of
+---                    scrolling with 'nowrap' or 'smoothscroll'.
+---                    Currently only affects "overlay" virt_text.
+--- - virt_text_repeat_linebreak : repeat the virtual text on
+---                                wrapped lines.
+--- - hl_mode : control how highlights are combined with the
+---             highlights of the text. Currently only affects
+---             virt_text highlights, but might affect `hl_group`
+---             in later versions.
+---   - "replace": only show the virt_text color. This is the default.
+---   - "combine": combine with background text color.
+---   - "blend": blend with background text color.
+---              Not supported for "inline" virt_text.
+---
+--- - virt_lines : virtual lines to add next to this mark
+---     This should be an array over lines, where each line in
+---     turn is an array over `[text, highlight]` tuples. In
+---     general, buffer and window options do not affect the
+---     display of the text. In particular 'wrap'
+---     and 'linebreak' options do not take effect, so
+---     the number of extra screen lines will always match
+---     the size of the array. However the 'tabstop' buffer
+---     option is still used for hard tabs. By default lines are
+---     placed below the buffer line containing the mark.
+---
+--- - virt_lines_above: place virtual lines above instead.
+--- - virt_lines_leftcol: Place extmarks in the leftmost
+---                       column of the window, bypassing
+---                       sign and number columns.
+---
+--- - ephemeral : for use with `nvim_set_decoration_provider()`
+---     callbacks. The mark will only be used for the current
+---     redraw cycle, and not be permantently stored in the
+---     buffer.
+--- - right_gravity : boolean that indicates the direction
+---     the extmark will be shifted in when new text is inserted
+---     (true for right, false for left). Defaults to true.
+--- - end_right_gravity : boolean that indicates the direction
+---     the extmark end position (if it exists) will be shifted
+---     in when new text is inserted (true for right, false
+---     for left). Defaults to false.
+--- - undo_restore : Restore the exact position of the mark
+---     if text around the mark was deleted and then restored by undo.
+---     Defaults to true.
+--- - invalidate : boolean that indicates whether to hide the
+---     extmark if the entirety of its range is deleted. For
+---     hidden marks, an "invalid" key is added to the "details"
+---     array of `nvim_buf_get_extmarks()` and family. If
+---     "undo_restore" is false, the extmark is deleted instead.
+--- - priority: a priority value for the highlight group, sign
+---     attribute or virtual text. For virtual text, item with
+---     highest priority is drawn last. For example treesitter
+---     highlighting uses a value of 100.
+--- - strict: boolean that indicates extmark should not be placed
+---     if the line or column value is past the end of the
+---     buffer or end of the line respectively. Defaults to true.
+--- - sign_text: string of length 1-2 used to display in the
+---     sign column.
+--- - sign_hl_group: name of the highlight group used to
+---     highlight the sign column text.
+--- - number_hl_group: name of the highlight group used to
+---     highlight the number column.
+--- - line_hl_group: name of the highlight group used to
+---     highlight the whole line.
+--- - cursorline_hl_group: name of the highlight group used to
+---     highlight the sign column text when the cursor is on
+---     the same line as the mark and 'cursorline' is enabled.
+--- - conceal: string which should be either empty or a single
+---     character. Enable concealing similar to `:syn-conceal`.
+---     When a character is supplied it is used as `:syn-cchar`.
+---     "hl_group" is used as highlight for the cchar if provided,
+---     otherwise it defaults to `hl-Conceal`.
+--- - spell: boolean indicating that spell checking should be
+---     performed within this extmark
+--- - ui_watched: boolean that indicates the mark should be drawn
+---     by a UI. When set, the UI will receive win_extmark events.
+---     Note: the mark is positioned by virt_text attributes. Can be
+---     used together with virt_text.
+--- - url: A URL to associate with this extmark. In the TUI, the OSC 8 control
+---     sequence is used to generate a clickable hyperlink to this URL.
+--- @return integer # Id of the created/updated extmark
 function vim.api.nvim_buf_set_extmark(buffer, ns_id, line, col, opts) end
 
 --- Sets a buffer-local `mapping` for the given mode.
 ---
+---
+--- @see vim.api.nvim_set_keymap
 --- @param buffer integer Buffer handle, or 0 for current buffer
 --- @param mode string
 --- @param lhs string
@@ -702,9 +714,9 @@ function vim.api.nvim_buf_set_keymap(buffer, mode, lhs, rhs, opts) end
 
 --- Sets (replaces) a line-range in the buffer.
 ---
---- Indexing is zero-based, end-exclusive. Negative indices are interpreted as
---- length+1+index: -1 refers to the index past the end. So to change or
---- delete the last element use start=-2 and end=-1.
+--- Indexing is zero-based, end-exclusive. Negative indices are interpreted
+--- as length+1+index: -1 refers to the index past the end. So to change
+--- or delete the last element use start=-2 and end=-1.
 ---
 --- To insert lines at a given index, set `start` and `end` to the same index.
 --- To delete a range of lines, set `replacement` to an empty array.
@@ -712,6 +724,8 @@ function vim.api.nvim_buf_set_keymap(buffer, mode, lhs, rhs, opts) end
 --- Out-of-bounds indices are clamped to the nearest valid value, unless
 --- `strict_indexing` is set.
 ---
+---
+--- @see vim.api.nvim_buf_set_text
 --- @param buffer integer Buffer handle, or 0 for current buffer
 --- @param start integer First line index
 --- @param end_ integer Last line index, exclusive
@@ -724,12 +738,18 @@ function vim.api.nvim_buf_set_lines(buffer, start, end_, strict_indexing, replac
 ---
 --- Marks are (1,0)-indexed. `api-indexing`
 ---
+--- Note:
+--- Passing 0 as line deletes the mark
+---
+---
+--- @see vim.api.nvim_buf_del_mark
+--- @see vim.api.nvim_buf_get_mark
 --- @param buffer integer Buffer to set the mark on
 --- @param name string Mark name
 --- @param line integer Line number
 --- @param col integer Column/row number
 --- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use.
---- @return boolean
+--- @return boolean # true if the mark was set, else false.
 function vim.api.nvim_buf_set_mark(buffer, name, line, col, opts) end
 
 --- Sets the full file name for a buffer, like `:file_f`
@@ -746,21 +766,21 @@ function vim.api.nvim_buf_set_option(buffer, name, value) end
 
 --- Sets (replaces) a range in the buffer
 ---
---- This is recommended over `nvim_buf_set_lines()` when only modifying parts
---- of a line, as extmarks will be preserved on non-modified parts of the
---- touched lines.
+--- This is recommended over `nvim_buf_set_lines()` when only modifying parts of
+--- a line, as extmarks will be preserved on non-modified parts of the touched
+--- lines.
 ---
 --- Indexing is zero-based. Row indices are end-inclusive, and column indices
 --- are end-exclusive.
 ---
---- To insert text at a given `(row, column)` location, use
---- `start_row = end_row = row` and `start_col = end_col = col`. To delete the
---- text in a range, use `replacement = {}`.
+--- To insert text at a given `(row, column)` location, use `start_row = end_row
+--- = row` and `start_col = end_col = col`. To delete the text in a range, use
+--- `replacement = {}`.
 ---
---- Prefer `nvim_buf_set_lines()` if you are only adding or deleting entire
---- lines.
+--- Note:
+--- Prefer |nvim_buf_set_lines()| (for performance) to add or delete entire lines.
+--- Prefer |nvim_paste()| or |nvim_put()| to insert (instead of replace) text at cursor.
 ---
---- Prefer `nvim_put()` if you want to insert text at the cursor position.
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
 --- @param start_row integer First line index
@@ -790,10 +810,10 @@ function vim.api.nvim_buf_set_virtual_text(buffer, src_id, line, chunks, opts) e
 ---
 --- On execution error: fails with Vimscript error, updates v:errmsg.
 ---
---- @param dict any Dictionary, or String evaluating to a Vimscript `self` dict
+--- @param dict any Dict, or String evaluating to a Vimscript `self` dict
 --- @param fn string Name of the function defined on the Vimscript dict
 --- @param args any[] Function arguments packed in an Array
---- @return any
+--- @return any # Result of the function call
 function vim.api.nvim_call_dict_function(dict, fn, args) end
 
 --- Calls a Vimscript function with the given arguments.
@@ -802,85 +822,83 @@ function vim.api.nvim_call_dict_function(dict, fn, args) end
 ---
 --- @param fn string Function to call
 --- @param args any[] Function arguments packed in an Array
---- @return any
+--- @return any # Result of the function call
 function vim.api.nvim_call_function(fn, args) end
 
---- Send data to channel `id`. For a job, it writes it to the stdin of the
---- process. For the stdio channel `channel-stdio`, it writes to Nvim's
---- stdout. For an internal terminal instance (`nvim_open_term()`) it writes
---- directly to terminal output. See `channel-bytes` for more information.
+--- Send data to channel `id`. For a job, it writes it to the
+--- stdin of the process. For the stdio channel `channel-stdio`,
+--- it writes to Nvim's stdout.  For an internal terminal instance
+--- (`nvim_open_term()`) it writes directly to terminal output.
+--- See `channel-bytes` for more information.
 ---
---- This function writes raw data, not RPC messages. If the channel was
---- created with `rpc=true` then the channel expects RPC messages, use
---- `vim.rpcnotify()` and `vim.rpcrequest()` instead.
+--- This function writes raw data, not RPC messages.  If the channel
+--- was created with `rpc=true` then the channel expects RPC
+--- messages, use `vim.rpcnotify()` and `vim.rpcrequest()` instead.
 ---
 --- @param chan integer id of the channel
 --- @param data string data to write. 8-bit clean: can contain NUL bytes.
 function vim.api.nvim_chan_send(chan, data) end
 
---- Clears all autocommands selected by {opts}. To delete autocmds see
---- `nvim_del_autocmd()`.
+--- Clears all autocommands selected by {opts}. To delete autocmds see `nvim_del_autocmd()`.
 ---
 --- @param opts vim.api.keyset.clear_autocmds Parameters
----             • event: (string|table) Examples:
----               • event: "pat1"
----               • event: { "pat1" }
----               • event: { "pat1", "pat2", "pat3" }
----             • pattern: (string|table)
----               • pattern or patterns to match exactly.
----                 • For example, if you have `*.py` as that pattern for the
----                   autocmd, you must pass `*.py` exactly to clear it.
----                   `test.py` will not match the pattern.
----               • defaults to clearing all patterns.
----               • NOTE: Cannot be used with {buffer}
----             • buffer: (bufnr)
----               • clear only `autocmd-buflocal` autocommands.
----               • NOTE: Cannot be used with {pattern}
----             • group: (string|int) The augroup name or id.
----               • NOTE: If not passed, will only delete autocmds not in any
----                 group.
+--- - event: (string|table)
+---      Examples:
+---      - event: "pat1"
+---      - event: { "pat1" }
+---      - event: { "pat1", "pat2", "pat3" }
+--- - pattern: (string|table)
+---     - pattern or patterns to match exactly.
+---         - For example, if you have `*.py` as that pattern for the autocmd,
+---           you must pass `*.py` exactly to clear it. `test.py` will not
+---           match the pattern.
+---     - defaults to clearing all patterns.
+---     - NOTE: Cannot be used with {buffer}
+--- - buffer: (bufnr)
+---     - clear only `autocmd-buflocal` autocommands.
+---     - NOTE: Cannot be used with {pattern}
+--- - group: (string|int) The augroup name or id.
+---     - NOTE: If not passed, will only delete autocmds *not* in any group.
 function vim.api.nvim_clear_autocmds(opts) end
 
 --- Executes an Ex command.
 ---
---- Unlike `nvim_command()` this command takes a structured Dictionary instead
---- of a String. This allows for easier construction and manipulation of an Ex
---- command. This also allows for things such as having spaces inside a
---- command argument, expanding filenames in a command that otherwise doesn't
---- expand filenames, etc. Command arguments may also be Number, Boolean or
---- String.
+--- Unlike `nvim_command()` this command takes a structured Dict instead of a String. This
+--- allows for easier construction and manipulation of an Ex command. This also allows for things
+--- such as having spaces inside a command argument, expanding filenames in a command that otherwise
+--- doesn't expand filenames, etc. Command arguments may also be Number, Boolean or String.
 ---
---- The first argument may also be used instead of count for commands that
---- support it in order to make their usage simpler with `vim.cmd()`. For
---- example, instead of `vim.cmd.bdelete{ count = 2 }`, you may do
---- `vim.cmd.bdelete(2)`.
+--- The first argument may also be used instead of count for commands that support it in order to
+--- make their usage simpler with `vim.cmd()`. For example, instead of
+--- `vim.cmd.bdelete{ count = 2 }`, you may do `vim.cmd.bdelete(2)`.
 ---
 --- On execution error: fails with Vimscript error, updates v:errmsg.
 ---
---- @param cmd vim.api.keyset.cmd Command to execute. Must be a Dictionary that can contain the
----            same values as the return value of `nvim_parse_cmd()` except
----            "addr", "nargs" and "nextcmd" which are ignored if provided.
----            All values except for "cmd" are optional.
+---
+--- @see vim.api.nvim_exec2
+--- @see vim.api.nvim_command
+--- @param cmd vim.api.keyset.cmd Command to execute. Must be a Dict that can contain the same values as
+--- the return value of `nvim_parse_cmd()` except "addr", "nargs" and "nextcmd"
+--- which are ignored if provided. All values except for "cmd" are optional.
 --- @param opts vim.api.keyset.cmd_opts Optional parameters.
----             • output: (boolean, default false) Whether to return command
----               output.
---- @return string
+--- - output: (boolean, default false) Whether to return command output.
+--- @return string # Command output (non-error, non-shell |:!|) if `output` is true, else empty string.
 function vim.api.nvim_cmd(cmd, opts) end
 
 --- Executes an Ex command.
 ---
 --- On execution error: fails with Vimscript error, updates v:errmsg.
 ---
---- Prefer using `nvim_cmd()` or `nvim_exec2()` over this. To evaluate
---- multiple lines of Vim script or an Ex command directly, use
---- `nvim_exec2()`. To construct an Ex command using a structured format and
---- then execute it, use `nvim_cmd()`. To modify an Ex command before
---- evaluating it, use `nvim_parse_cmd()` in conjunction with `nvim_cmd()`.
+--- Prefer using `nvim_cmd()` or `nvim_exec2()` over this. To evaluate multiple lines of Vim script
+--- or an Ex command directly, use `nvim_exec2()`. To construct an Ex command using a structured
+--- format and then execute it, use `nvim_cmd()`. To modify an Ex command before evaluating it, use
+--- `nvim_parse_cmd()` in conjunction with `nvim_cmd()`.
 ---
 --- @param command string Ex command string
 function vim.api.nvim_command(command) end
 
 --- @deprecated
+--- @see vim.api.nvim_exec2
 --- @param command string
 --- @return string
 function vim.api.nvim_command_output(command) end
@@ -890,106 +908,99 @@ function vim.api.nvim_command_output(command) end
 --- To get an existing group id, do:
 ---
 --- ```lua
----     local id = vim.api.nvim_create_augroup("MyGroup", {
----         clear = false
----     })
+--- local id = vim.api.nvim_create_augroup("MyGroup", {
+---     clear = false
+--- })
 --- ```
 ---
----
+--- @see `:help autocmd-groups`
 --- @param name string String: The name of the group
---- @param opts vim.api.keyset.create_augroup Dictionary Parameters
----             • clear (bool) optional: defaults to true. Clear existing
----               commands if the group already exists `autocmd-groups`.
---- @return integer
+--- @param opts vim.api.keyset.create_augroup Dict Parameters
+--- - clear (bool) optional: defaults to true. Clear existing
+--- commands if the group already exists `autocmd-groups`.
+--- @return integer # Integer id of the created group.
 function vim.api.nvim_create_augroup(name, opts) end
 
---- Creates an `autocommand` event handler, defined by `callback` (Lua
---- function or Vimscript function name string) or `command` (Ex command
---- string).
+--- Creates an `autocommand` event handler, defined by `callback` (Lua function or Vimscript
+--- function _name_ string) or `command` (Ex command string).
 ---
 --- Example using Lua callback:
 ---
 --- ```lua
----     vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
----       pattern = {"*.c", "*.h"},
----       callback = function(ev)
----         print(string.format('event fired: %s', vim.inspect(ev)))
----       end
----     })
+--- vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
+---   pattern = {"*.c", "*.h"},
+---   callback = function(ev)
+---     print(string.format('event fired: %s', vim.inspect(ev)))
+---   end
+--- })
 --- ```
 ---
 --- Example using an Ex command as the handler:
 ---
 --- ```lua
----     vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
----       pattern = {"*.c", "*.h"},
----       command = "echo 'Entering a C or C++ file'",
----     })
+--- vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
+---   pattern = {"*.c", "*.h"},
+---   command = "echo 'Entering a C or C++ file'",
+--- })
 --- ```
 ---
---- Note: `pattern` is NOT automatically expanded (unlike with `:autocmd`),
---- thus names like "$HOME" and "~" must be expanded explicitly:
+--- Note: `pattern` is NOT automatically expanded (unlike with `:autocmd`), thus names like "$HOME"
+--- and "~" must be expanded explicitly:
 ---
 --- ```lua
----     pattern = vim.fn.expand("~") .. "/some/path/*.py"
+--- pattern = vim.fn.expand("~") .. "/some/path/*.py"
 --- ```
 ---
----
---- @param event any (string|array) Event(s) that will trigger the handler
----              (`callback` or `command`).
+--- @see `:help autocommand`
+--- @see vim.api.nvim_del_autocmd
+--- @param event any (string|array) Event(s) that will trigger the handler (`callback` or `command`).
 --- @param opts vim.api.keyset.create_autocmd Options dict:
----             • group (string|integer) optional: autocommand group name or
----               id to match against.
----             • pattern (string|array) optional: pattern(s) to match
----               literally `autocmd-pattern`.
----             • buffer (integer) optional: buffer number for buffer-local
----               autocommands `autocmd-buflocal`. Cannot be used with
----               {pattern}.
----             • desc (string) optional: description (for documentation and
----               troubleshooting).
----             • callback (function|string) optional: Lua function (or
----               Vimscript function name, if string) called when the event(s)
----               is triggered. Lua callback can return a truthy value (not
----               `false` or `nil`) to delete the autocommand. Receives one
----               argument, a table with these keys:              *event-args*
----               • id: (number) autocommand id
----               • event: (string) name of the triggered event
----                 `autocmd-events`
----               • group: (number|nil) autocommand group id, if any
----               • match: (string) expanded value of <amatch>
----               • buf: (number) expanded value of <abuf>
----               • file: (string) expanded value of <afile>
----               • data: (any) arbitrary data passed from
----                 `nvim_exec_autocmds()`                        *event-data*
----             • command (string) optional: Vim command to execute on event.
----               Cannot be used with {callback}
----             • once (boolean) optional: defaults to false. Run the
----               autocommand only once `autocmd-once`.
----             • nested (boolean) optional: defaults to false. Run nested
----               autocommands `autocmd-nested`.
---- @return integer
+--- - group (string|integer) optional: autocommand group name or id to match against.
+--- - pattern (string|array) optional: pattern(s) to match literally `autocmd-pattern`.
+--- - buffer (integer) optional: buffer number for buffer-local autocommands
+--- `autocmd-buflocal`. Cannot be used with {pattern}.
+--- - desc (string) optional: description (for documentation and troubleshooting).
+--- - callback (function|string) optional: Lua function (or Vimscript function name, if
+--- string) called when the event(s) is triggered. Lua callback can return a truthy
+--- value (not `false` or `nil`) to delete the autocommand. Receives one argument,
+--- a table with these keys: [event-args]()
+---     - id: (number) autocommand id
+---     - event: (string) name of the triggered event `autocmd-events`
+---     - group: (number|nil) autocommand group id, if any
+---     - match: (string) expanded value of [<amatch>]
+---     - buf: (number) expanded value of [<abuf>]
+---     - file: (string) expanded value of [<afile>]
+---     - data: (any) arbitrary data passed from [nvim_exec_autocmds()] [event-data]()
+--- - command (string) optional: Vim command to execute on event. Cannot be used with
+--- {callback}
+--- - once (boolean) optional: defaults to false. Run the autocommand
+--- only once `autocmd-once`.
+--- - nested (boolean) optional: defaults to false. Run nested
+--- autocommands `autocmd-nested`.
+--- @return integer # Autocommand id (number)
 function vim.api.nvim_create_autocmd(event, opts) end
 
 --- Creates a new, empty, unnamed buffer.
 ---
+--- @see buf_open_scratch
 --- @param listed boolean Sets 'buflisted'
 --- @param scratch boolean Creates a "throwaway" `scratch-buffer` for temporary work
----                (always 'nomodified'). Also sets 'nomodeline' on the
----                buffer.
---- @return integer
+--- (always 'nomodified'). Also sets 'nomodeline' on the buffer.
+--- @return integer # Buffer handle, or 0 on error
+---
 function vim.api.nvim_create_buf(listed, scratch) end
 
---- Creates a new namespace or gets an existing one.               *namespace*
+--- Creates a new namespace or gets an existing one. [namespace]()
 ---
 --- Namespaces are used for buffer highlights and virtual text, see
 --- `nvim_buf_add_highlight()` and `nvim_buf_set_extmark()`.
 ---
 --- Namespaces can be named or anonymous. If `name` matches an existing
---- namespace, the associated id is returned. If `name` is an empty string a
---- new, anonymous namespace is created.
+--- namespace, the associated id is returned. If `name` is an empty string
+--- a new, anonymous namespace is created.
 ---
 --- @param name string Namespace name or empty string
---- @return integer
+--- @return integer # Namespace id
 function vim.api.nvim_create_namespace(name) end
 
 --- Creates a global `user-commands` command.
@@ -999,70 +1010,57 @@ function vim.api.nvim_create_namespace(name) end
 --- Example:
 ---
 --- ```vim
----     :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {'bang': v:true})
----     :SayHello
----     Hello world!
+--- :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {'bang': v:true})
+--- :SayHello
+--- Hello world!
 --- ```
 ---
----
---- @param name string Name of the new user command. Must begin with an uppercase
----             letter.
---- @param command any Replacement command to execute when this user command is
----                executed. When called from Lua, the command can also be a
----                Lua function. The function is called with a single table
----                argument that contains the following keys:
----                • name: (string) Command name
----                • args: (string) The args passed to the command, if any
----                  <args>
----                • fargs: (table) The args split by unescaped whitespace
----                  (when more than one argument is allowed), if any <f-args>
----                • nargs: (string) Number of arguments `:command-nargs`
----                • bang: (boolean) "true" if the command was executed with a
----                  ! modifier <bang>
----                • line1: (number) The starting line of the command range
----                  <line1>
----                • line2: (number) The final line of the command range
----                  <line2>
----                • range: (number) The number of items in the command range:
----                  0, 1, or 2 <range>
----                • count: (number) Any count supplied <count>
----                • reg: (string) The optional register, if specified <reg>
----                • mods: (string) Command modifiers, if any <mods>
----                • smods: (table) Command modifiers in a structured format.
----                  Has the same structure as the "mods" key of
----                  `nvim_parse_cmd()`.
+--- @param name string Name of the new user command. Must begin with an uppercase letter.
+--- @param command any Replacement command to execute when this user command is executed. When called
+--- from Lua, the command can also be a Lua function. The function is called with a
+--- single table argument that contains the following keys:
+--- - name: (string) Command name
+--- - args: (string) The args passed to the command, if any [<args>]
+--- - fargs: (table) The args split by unescaped whitespace (when more than one
+--- argument is allowed), if any [<f-args>]
+--- - nargs: (string) Number of arguments `:command-nargs`
+--- - bang: (boolean) "true" if the command was executed with a ! modifier [<bang>]
+--- - line1: (number) The starting line of the command range [<line1>]
+--- - line2: (number) The final line of the command range [<line2>]
+--- - range: (number) The number of items in the command range: 0, 1, or 2 [<range>]
+--- - count: (number) Any count supplied [<count>]
+--- - reg: (string) The optional register, if specified [<reg>]
+--- - mods: (string) Command modifiers, if any [<mods>]
+--- - smods: (table) Command modifiers in a structured format. Has the same
+--- structure as the "mods" key of `nvim_parse_cmd()`.
 --- @param opts vim.api.keyset.user_command Optional `command-attributes`.
----             • Set boolean attributes such as `:command-bang` or
----               `:command-bar` to true (but not `:command-buffer`, use
----               `nvim_buf_create_user_command()` instead).
----             • "complete" `:command-complete` also accepts a Lua function
----               which works like `:command-completion-customlist`.
----             • Other parameters:
----               • desc: (string) Used for listing the command when a Lua
----                 function is used for {command}.
----               • force: (boolean, default true) Override any previous
----                 definition.
----               • preview: (function) Preview callback for 'inccommand'
----                 `:command-preview`
+--- - Set boolean attributes such as `:command-bang` or `:command-bar` to true (but
+---   not `:command-buffer`, use `nvim_buf_create_user_command()` instead).
+--- - "complete" `:command-complete` also accepts a Lua function which works like
+---   `:command-completion-customlist`.
+--- - Other parameters:
+---   - desc: (string) Used for listing the command when a Lua function is used for
+---                    {command}.
+---   - force: (boolean, default true) Override any previous definition.
+---   - preview: (function) Preview callback for 'inccommand' `:command-preview`
 function vim.api.nvim_create_user_command(name, command, opts) end
 
 --- Delete an autocommand group by id.
 ---
 --- To get a group id one can use `nvim_get_autocmds()`.
 ---
---- NOTE: behavior differs from `:augroup-delete`. When deleting a group,
---- autocommands contained in this group will also be deleted and cleared.
---- This group will no longer exist.
----
+--- NOTE: behavior differs from `:augroup-delete`. When deleting a group, autocommands contained in
+--- this group will also be deleted and cleared. This group will no longer exist.
+--- @see vim.api.nvim_del_augroup_by_name
+--- @see vim.api.nvim_create_augroup
 --- @param id integer Integer The id of the group.
 function vim.api.nvim_del_augroup_by_id(id) end
 
 --- Delete an autocommand group by name.
 ---
---- NOTE: behavior differs from `:augroup-delete`. When deleting a group,
---- autocommands contained in this group will also be deleted and cleared.
---- This group will no longer exist.
----
+--- NOTE: behavior differs from `:augroup-delete`. When deleting a group, autocommands contained in
+--- this group will also be deleted and cleared. This group will no longer exist.
+--- @see `:help autocmd-groups`
 --- @param name string String The name of the group.
 function vim.api.nvim_del_augroup_by_name(name) end
 
@@ -1079,14 +1077,20 @@ function vim.api.nvim_del_current_line() end
 ---
 --- To unmap a buffer-local mapping, use `nvim_buf_del_keymap()`.
 ---
+--- @see vim.api.nvim_set_keymap
 --- @param mode string
 --- @param lhs string
 function vim.api.nvim_del_keymap(mode, lhs) end
 
 --- Deletes an uppercase/file named mark. See `mark-motions`.
 ---
+--- Note:
+--- Lowercase name (or other buffer-local mark) is an error.
+---
+--- @see vim.api.nvim_buf_del_mark
+--- @see vim.api.nvim_get_mark
 --- @param name string Mark name
---- @return boolean
+--- @return boolean # true if the mark was deleted, else false.
 function vim.api.nvim_del_mark(name) end
 
 --- Delete a user-defined command.
@@ -1102,14 +1106,13 @@ function vim.api.nvim_del_var(name) end
 --- Echo a message.
 ---
 --- @param chunks any[] A list of `[text, hl_group]` arrays, each representing a
----               text chunk with specified highlight. `hl_group` element can
----               be omitted for no highlight.
+--- text chunk with specified highlight. `hl_group` element
+--- can be omitted for no highlight.
 --- @param history boolean if true, add to `message-history`.
 --- @param opts vim.api.keyset.echo_opts Optional parameters.
----             • verbose: Message was printed as a result of 'verbose' option
----               if Nvim was invoked with -V3log_file, the message will be
----               redirected to the log_file and suppressed from direct
----               output.
+--- - verbose: Message was printed as a result of 'verbose' option
+---   if Nvim was invoked with -V3log_file, the message will be
+---   redirected to the log_file and suppressed from direct output.
 function vim.api.nvim_echo(chunks, history, opts) end
 
 --- Writes a message to the Vim error buffer. Does not append "\n", the
@@ -1121,39 +1124,43 @@ function vim.api.nvim_err_write(str) end
 --- Writes a message to the Vim error buffer. Appends "\n", so the buffer is
 --- flushed (and displayed).
 ---
+--- @see vim.api.nvim_err_write
 --- @param str string Message
 function vim.api.nvim_err_writeln(str) end
 
---- Evaluates a Vimscript `expression`. Dictionaries and Lists are recursively
---- expanded.
+--- Evaluates a Vimscript `expression`. Dicts and Lists are recursively expanded.
 ---
 --- On execution error: fails with Vimscript error, updates v:errmsg.
 ---
 --- @param expr string Vimscript expression string
---- @return any
+--- @return any # Evaluation result or expanded object
 function vim.api.nvim_eval(expr) end
 
 --- Evaluates statusline string.
 ---
 --- @param str string Statusline string (see 'statusline').
 --- @param opts vim.api.keyset.eval_statusline Optional parameters.
----             • winid: (number) `window-ID` of the window to use as context
----               for statusline.
----             • maxwidth: (number) Maximum width of statusline.
----             • fillchar: (string) Character to fill blank spaces in the
----               statusline (see 'fillchars'). Treated as single-width even
----               if it isn't.
----             • highlights: (boolean) Return highlight information.
----             • use_winbar: (boolean) Evaluate winbar instead of statusline.
----             • use_tabline: (boolean) Evaluate tabline instead of
----               statusline. When true, {winid} is ignored. Mutually
----               exclusive with {use_winbar}.
----             • use_statuscol_lnum: (number) Evaluate statuscolumn for this
----               line number instead of statusline.
---- @return table<string,any>
+--- - winid: (number) `window-ID` of the window to use as context for statusline.
+--- - maxwidth: (number) Maximum width of statusline.
+--- - fillchar: (string) Character to fill blank spaces in the statusline (see
+---                      'fillchars'). Treated as single-width even if it isn't.
+--- - highlights: (boolean) Return highlight information.
+--- - use_winbar: (boolean) Evaluate winbar instead of statusline.
+--- - use_tabline: (boolean) Evaluate tabline instead of statusline. When true, {winid}
+---                          is ignored. Mutually exclusive with {use_winbar}.
+--- - use_statuscol_lnum: (number) Evaluate statuscolumn for this line number instead of statusline.
+--- @return table<string,any> # Dict containing statusline information, with these keys:
+--- - str: (string) Characters that will be displayed on the statusline.
+--- - width: (number) Display width of the statusline.
+--- - highlights: Array containing highlight information of the statusline. Only included when
+---               the "highlights" key in {opts} is true. Each element of the array is a
+---               |Dict| with these keys:
+---     - start: (number) Byte index (0-based) of first character that uses the highlight.
+---     - group: (string) Name of highlight group.
 function vim.api.nvim_eval_statusline(str, opts) end
 
 --- @deprecated
+--- @see vim.api.nvim_exec2
 --- @param src string
 --- @param output boolean
 --- @return string
@@ -1162,33 +1169,38 @@ function vim.api.nvim_exec(src, output) end
 --- Executes Vimscript (multiline block of Ex commands), like anonymous
 --- `:source`.
 ---
---- Unlike `nvim_command()` this function supports heredocs, script-scope
---- (s:), etc.
+--- Unlike `nvim_command()` this function supports heredocs, script-scope (s:),
+--- etc.
 ---
 --- On execution error: fails with Vimscript error, updates v:errmsg.
 ---
+---
+--- @see `:help execute()`
+--- @see vim.api.nvim_command
+--- @see vim.api.nvim_cmd
 --- @param src string Vimscript code
 --- @param opts vim.api.keyset.exec_opts Optional parameters.
----             • output: (boolean, default false) Whether to capture and
----               return all (non-error, non-shell `:!`) output.
---- @return table<string,any>
+--- - output: (boolean, default false) Whether to capture and return
+---           all (non-error, non-shell `:!`) output.
+--- @return table<string,any> # Dict containing information about execution, with these keys:
+--- - output: (string|nil) Output if `opts.output` is true.
 function vim.api.nvim_exec2(src, opts) end
 
---- Execute all autocommands for {event} that match the corresponding {opts}
---- `autocmd-execute`.
----
+--- Execute all autocommands for {event} that match the corresponding
+---  {opts} `autocmd-execute`.
+--- @see `:help :doautocmd`
 --- @param event any (String|Array) The event or events to execute
---- @param opts vim.api.keyset.exec_autocmds Dictionary of autocommand options:
----             • group (string|integer) optional: the autocommand group name
----               or id to match against. `autocmd-groups`.
----             • pattern (string|array) optional: defaults to "*"
----               `autocmd-pattern`. Cannot be used with {buffer}.
----             • buffer (integer) optional: buffer number `autocmd-buflocal`.
----               Cannot be used with {pattern}.
----             • modeline (bool) optional: defaults to true. Process the
----               modeline after the autocommands <nomodeline>.
----             • data (any): arbitrary data to send to the autocommand
----               callback. See `nvim_create_autocmd()` for details.
+--- @param opts vim.api.keyset.exec_autocmds Dict of autocommand options:
+--- - group (string|integer) optional: the autocommand group name or
+--- id to match against. `autocmd-groups`.
+--- - pattern (string|array) optional: defaults to "*" `autocmd-pattern`. Cannot be used
+--- with {buffer}.
+--- - buffer (integer) optional: buffer number `autocmd-buflocal`. Cannot be used with
+--- {pattern}.
+--- - modeline (bool) optional: defaults to true. Process the
+--- modeline after the autocommands [<nomodeline>].
+--- - data (any): arbitrary data to send to the autocommand callback. See
+--- `nvim_create_autocmd()` for details.
 function vim.api.nvim_exec_autocmds(event, opts) end
 
 --- Sends input-keys to Nvim, subject to various quirks controlled by `mode`
@@ -1196,31 +1208,34 @@ function vim.api.nvim_exec_autocmds(event, opts) end
 ---
 --- On execution error: does not fail, but updates v:errmsg.
 ---
---- To input sequences like <C-o> use `nvim_replace_termcodes()` (typically
+--- To input sequences like [<C-o>] use `nvim_replace_termcodes()` (typically
 --- with escape_ks=false) to replace `keycodes`, then pass the result to
 --- nvim_feedkeys().
 ---
 --- Example:
 ---
 --- ```vim
----     :let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true)
----     :call nvim_feedkeys(key, 'n', v:false)
+--- :let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true)
+--- :call nvim_feedkeys(key, 'n', v:false)
 --- ```
 ---
----
+--- @see feedkeys()
+--- @see vim_strsave_escape_ks
 --- @param keys string to be typed
 --- @param mode string behavior flags, see `feedkeys()`
---- @param escape_ks boolean If true, escape K_SPECIAL bytes in `keys`. This should be
----                  false if you already used `nvim_replace_termcodes()`, and
----                  true otherwise.
+--- @param escape_ks boolean If true, escape K_SPECIAL bytes in `keys`.
+--- This should be false if you already used
+--- `nvim_replace_termcodes()`, and true otherwise.
 function vim.api.nvim_feedkeys(keys, mode, escape_ks) end
 
 --- Gets the option information for all options.
 ---
---- The dictionary has the full option names as keys and option metadata
---- dictionaries as detailed at `nvim_get_option_info2()`.
+--- The dict has the full option names as keys and option metadata dicts as detailed at
+--- `nvim_get_option_info2()`.
 ---
---- @return table<string,any>
+---
+--- @see vim.api.nvim_get_commands
+--- @return table<string,any> # dict of all options
 function vim.api.nvim_get_all_options_info() end
 
 --- Get all autocommands that match the corresponding {opts}.
@@ -1228,39 +1243,68 @@ function vim.api.nvim_get_all_options_info() end
 --- These examples will get autocommands matching ALL the given criteria:
 ---
 --- ```lua
----     -- Matches all criteria
----     autocommands = vim.api.nvim_get_autocmds({
----       group = "MyGroup",
----       event = {"BufEnter", "BufWinEnter"},
----       pattern = {"*.c", "*.h"}
----     })
----
----     -- All commands from one group
----     autocommands = vim.api.nvim_get_autocmds({
----       group = "MyGroup",
----     })
+--- -- Matches all criteria
+--- autocommands = vim.api.nvim_get_autocmds({
+---   group = "MyGroup",
+---   event = {"BufEnter", "BufWinEnter"},
+---   pattern = {"*.c", "*.h"}
+--- })
+---
+--- -- All commands from one group
+--- autocommands = vim.api.nvim_get_autocmds({
+---   group = "MyGroup",
+--- })
 --- ```
 ---
---- NOTE: When multiple patterns or events are provided, it will find all the
---- autocommands that match any combination of them.
----
---- @param opts vim.api.keyset.get_autocmds Dictionary with at least one of the following:
----             • group (string|integer): the autocommand group name or id to
----               match against.
----             • event (string|array): event or events to match against
----               `autocmd-events`.
----             • pattern (string|array): pattern or patterns to match against
----               `autocmd-pattern`. Cannot be used with {buffer}
----             • buffer: Buffer number or list of buffer numbers for buffer
----               local autocommands `autocmd-buflocal`. Cannot be used with
----               {pattern}
---- @return vim.api.keyset.get_autocmds.ret[]
+--- NOTE: When multiple patterns or events are provided, it will find all the autocommands that
+--- match any combination of them.
+---
+--- @param opts vim.api.keyset.get_autocmds Dict with at least one of the following:
+--- - group (string|integer): the autocommand group name or id to match against.
+--- - event (string|array): event or events to match against `autocmd-events`.
+--- - pattern (string|array): pattern or patterns to match against `autocmd-pattern`.
+--- Cannot be used with {buffer}
+--- - buffer: Buffer number or list of buffer numbers for buffer local autocommands
+--- `autocmd-buflocal`. Cannot be used with {pattern}
+--- @return vim.api.keyset.get_autocmds.ret[] # Array of autocommands matching the criteria, with each item
+--- containing the following fields:
+--- - id (number): the autocommand id (only when defined with the API).
+--- - group (integer): the autocommand group id.
+--- - group_name (string): the autocommand group name.
+--- - desc (string): the autocommand description.
+--- - event (string): the autocommand event.
+--- - command (string): the autocommand command. Note: this will be empty if a callback is set.
+--- - callback (function|string|nil): Lua function or name of a Vim script function
+---   which is executed when this autocommand is triggered.
+--- - once (boolean): whether the autocommand is only run once.
+--- - pattern (string): the autocommand pattern.
+---   If the autocommand is buffer local |autocmd-buffer-local|:
+--- - buflocal (boolean): true if the autocommand is buffer local.
+--- - buffer (number): the buffer number.
 function vim.api.nvim_get_autocmds(opts) end
 
 --- Gets information about a channel.
 ---
 --- @param chan integer channel_id, or 0 for current channel
---- @return table<string,any>
+--- @return table<string,any> # Channel info dict with these keys:
+--- - "id"       Channel id.
+--- - "argv"     (optional) Job arguments list.
+--- - "stream"   Stream underlying the channel.
+---      - "stdio"      stdin and stdout of this Nvim instance
+---      - "stderr"     stderr of this Nvim instance
+---      - "socket"     TCP/IP socket or named pipe
+---      - "job"        Job with communication over its stdio.
+--- -  "mode"    How data received on the channel is interpreted.
+---      - "bytes"      Send and receive raw bytes.
+---      - "terminal"   |terminal| instance interprets ASCII sequences.
+---      - "rpc"        |RPC| communication on the channel is active.
+--- -  "pty"     (optional) Name of pseudoterminal. On a POSIX system this is a device path like
+---              "/dev/pts/1". If unknown, the key will still be present if a pty is used (e.g.
+---              for conpty on Windows).
+--- -  "buffer"  (optional) Buffer connected to |terminal| instance.
+--- -  "client"  (optional) Info about the peer (client on the other end of the RPC channel),
+---              which it provided via |nvim_set_client_info()|.
+---
 function vim.api.nvim_get_chan_info(chan) end
 
 --- Returns the 24-bit RGB value of a `nvim_get_color_map()` color name or
@@ -1269,13 +1313,12 @@ function vim.api.nvim_get_chan_info(chan) end
 --- Example:
 ---
 --- ```vim
----     :echo nvim_get_color_by_name("Pink")
----     :echo nvim_get_color_by_name("#cbcbcb")
+--- :echo nvim_get_color_by_name("Pink")
+--- :echo nvim_get_color_by_name("#cbcbcb")
 --- ```
 ---
----
 --- @param name string Color name or "#rrggbb" string
---- @return integer
+--- @return integer # 24-bit RGB value, or -1 for invalid argument.
 function vim.api.nvim_get_color_by_name(name) end
 
 --- Returns a map of color names and RGB values.
@@ -1283,67 +1326,75 @@ function vim.api.nvim_get_color_by_name(name) end
 --- Keys are color names (e.g. "Aqua") and values are 24-bit RGB color values
 --- (e.g. 65535).
 ---
---- @return table<string,integer>
+--- @return table<string,integer> # Map of color names and RGB values.
 function vim.api.nvim_get_color_map() end
 
 --- Gets a map of global (non-buffer-local) Ex commands.
 ---
 --- Currently only `user-commands` are supported, not builtin Ex commands.
 ---
---- @param opts vim.api.keyset.get_commands Optional parameters. Currently only supports {"builtin":false}
---- @return table<string,any>
+---
+--- @see vim.api.nvim_get_all_options_info
+--- @param opts vim.api.keyset.get_commands Optional parameters. Currently only supports
+--- {"builtin":false}
+--- @return table<string,any> # Map of maps describing commands.
 function vim.api.nvim_get_commands(opts) end
 
 --- Gets a map of the current editor state.
 ---
 --- @param opts vim.api.keyset.context Optional parameters.
----             • types: List of `context-types` ("regs", "jumps", "bufs",
----               "gvars", …) to gather, or empty for "all".
---- @return table<string,any>
+--- - types:  List of `context-types` ("regs", "jumps", "bufs",
+---   "gvars", …) to gather, or empty for "all".
+--- @return table<string,any> # map of global |context|.
 function vim.api.nvim_get_context(opts) end
 
 --- Gets the current buffer.
 ---
---- @return integer
+--- @return integer # Buffer handle
 function vim.api.nvim_get_current_buf() end
 
 --- Gets the current line.
 ---
---- @return string
+--- @return string # Current line string
 function vim.api.nvim_get_current_line() end
 
 --- Gets the current tabpage.
 ---
---- @return integer
+--- @return integer # Tabpage handle
 function vim.api.nvim_get_current_tabpage() end
 
 --- Gets the current window.
 ---
---- @return integer
+--- @return integer # Window handle
 function vim.api.nvim_get_current_win() end
 
 --- Gets all or specific highlight groups in a namespace.
 ---
---- @param ns_id integer Get highlight groups for namespace ns_id
----              `nvim_get_namespaces()`. Use 0 to get global highlight groups
----              `:highlight`.
+--- Note:
+--- When the `link` attribute is defined in the highlight definition
+--- map, other attributes will not be taking effect (see |:hi-link|).
+---
+---
+--- @param ns_id integer Get highlight groups for namespace ns_id `nvim_get_namespaces()`.
+--- Use 0 to get global highlight groups `:highlight`.
 --- @param opts vim.api.keyset.get_highlight Options dict:
----             • name: (string) Get a highlight definition by name.
----             • id: (integer) Get a highlight definition by id.
----             • link: (boolean, default true) Show linked group name instead
----               of effective definition `:hi-link`.
----             • create: (boolean, default true) When highlight group doesn't
----               exist create it.
---- @return vim.api.keyset.hl_info
+--- - name: (string) Get a highlight definition by name.
+--- - id: (integer) Get a highlight definition by id.
+--- - link: (boolean, default true) Show linked group name instead of effective definition `:hi-link`.
+--- - create: (boolean, default true) When highlight group doesn't exist create it.
+--- @return vim.api.keyset.get_hl_info # Highlight groups as a map from group name to a highlight definition map as in |nvim_set_hl()|,
+--- or only a single highlight definition map if requested by name or id.
 function vim.api.nvim_get_hl(ns_id, opts) end
 
 --- @deprecated
+--- @see vim.api.nvim_get_hl_by_name
 --- @param hl_id integer
 --- @param rgb boolean
 --- @return table<string,any>
 function vim.api.nvim_get_hl_by_id(hl_id, rgb) end
 
 --- @deprecated
+--- @see vim.api.nvim_get_hl_by_id
 --- @param name string
 --- @param rgb boolean
 --- @return table<string,any>
@@ -1352,7 +1403,6 @@ function vim.api.nvim_get_hl_by_name(name, rgb) end
 --- Gets a highlight group by name
 ---
 --- similar to `hlID()`, but allocates a new ID if not present.
----
 --- @param name string
 --- @return integer
 function vim.api.nvim_get_hl_id_by_name(name) end
@@ -1360,39 +1410,46 @@ function vim.api.nvim_get_hl_id_by_name(name) end
 --- Gets the active highlight namespace.
 ---
 --- @param opts vim.api.keyset.get_ns Optional parameters
----             • winid: (number) `window-ID` for retrieving a window's
----               highlight namespace. A value of -1 is returned when
----               `nvim_win_set_hl_ns()` has not been called for the window
----               (or was called with a namespace of -1).
---- @return integer
+--- - winid: (number) `window-ID` for retrieving a window's highlight
+---   namespace. A value of -1 is returned when `nvim_win_set_hl_ns()`
+---   has not been called for the window (or was called with a namespace
+---   of -1).
+--- @return integer # Namespace id, or -1
 function vim.api.nvim_get_hl_ns(opts) end
 
 --- Gets a list of global (non-buffer-local) `mapping` definitions.
 ---
 --- @param mode string Mode short-name ("n", "i", "v", ...)
---- @return vim.api.keyset.keymap[]
+--- @return vim.api.keyset.keymap[] # Array of |maparg()|-like dictionaries describing mappings.
+--- The "buffer" key is always zero.
 function vim.api.nvim_get_keymap(mode) end
 
 --- Returns a `(row, col, buffer, buffername)` tuple representing the position
---- of the uppercase/file named mark. "End of line" column position is
---- returned as `v:maxcol` (big number). See `mark-motions`.
+--- of the uppercase/file named mark. "End of line" column position is returned
+--- as `v:maxcol` (big number). See `mark-motions`.
 ---
 --- Marks are (1,0)-indexed. `api-indexing`
 ---
+--- Note:
+--- Lowercase name (or other buffer-local mark) is an error.
+---
+--- @see vim.api.nvim_buf_set_mark
+--- @see vim.api.nvim_del_mark
 --- @param name string Mark name
 --- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use.
---- @return vim.api.keyset.get_mark
+--- @return vim.api.keyset.get_mark # 4-tuple (row, col, buffer, buffername), (0, 0, 0, '') if the mark is
+--- not set.
 function vim.api.nvim_get_mark(name, opts) end
 
---- Gets the current mode. `mode()` "blocking" is true if Nvim is waiting for
---- input.
+--- Gets the current mode. `mode()`
+--- "blocking" is true if Nvim is waiting for input.
 ---
---- @return vim.api.keyset.get_mode
+--- @return vim.api.keyset.get_mode # Dict { "mode": String, "blocking": Boolean }
 function vim.api.nvim_get_mode() end
 
 --- Gets existing, non-anonymous `namespace`s.
 ---
---- @return table<string,integer>
+--- @return table<string,integer> # dict that maps from names to namespace ids.
 function vim.api.nvim_get_namespaces() end
 
 --- @deprecated
@@ -1407,100 +1464,113 @@ function vim.api.nvim_get_option_info(name) end
 
 --- Gets the option information for one option from arbitrary buffer or window
 ---
---- Resulting dictionary has keys:
---- • name: Name of the option (like 'filetype')
---- • shortname: Shortened name of the option (like 'ft')
---- • type: type of option ("string", "number" or "boolean")
---- • default: The default value for the option
---- • was_set: Whether the option was set.
---- • last_set_sid: Last set script id (if any)
---- • last_set_linenr: line number where option was set
---- • last_set_chan: Channel where option was set (0 for local)
---- • scope: one of "global", "win", or "buf"
---- • global_local: whether win or buf option has a global value
---- • commalist: List of comma separated values
---- • flaglist: List of single char flags
----
---- When {scope} is not provided, the last set information applies to the
---- local value in the current buffer or window if it is available, otherwise
---- the global value information is returned. This behavior can be disabled by
+--- Resulting dict has keys:
+--- - name: Name of the option (like 'filetype')
+--- - shortname: Shortened name of the option (like 'ft')
+--- - type: type of option ("string", "number" or "boolean")
+--- - default: The default value for the option
+--- - was_set: Whether the option was set.
+---
+--- - last_set_sid: Last set script id (if any)
+--- - last_set_linenr: line number where option was set
+--- - last_set_chan: Channel where option was set (0 for local)
+---
+--- - scope: one of "global", "win", or "buf"
+--- - global_local: whether win or buf option has a global value
+---
+--- - commalist: List of comma separated values
+--- - flaglist: List of single char flags
+---
+--- When {scope} is not provided, the last set information applies to the local
+--- value in the current buffer or window if it is available, otherwise the
+--- global value information is returned. This behavior can be disabled by
 --- explicitly specifying {scope} in the {opts} table.
 ---
 --- @param name string Option name
 --- @param opts vim.api.keyset.option Optional parameters
----             • scope: One of "global" or "local". Analogous to `:setglobal`
----               and `:setlocal`, respectively.
----             • win: `window-ID`. Used for getting window local options.
----             • buf: Buffer number. Used for getting buffer local options.
----               Implies {scope} is "local".
---- @return vim.api.keyset.get_option_info
+--- - scope: One of "global" or "local". Analogous to
+--- `:setglobal` and `:setlocal`, respectively.
+--- - win: `window-ID`. Used for getting window local options.
+--- - buf: Buffer number. Used for getting buffer local options.
+---        Implies {scope} is "local".
+--- @return vim.api.keyset.get_option_info # Option Information
 function vim.api.nvim_get_option_info2(name, opts) end
 
 --- Gets the value of an option. The behavior of this function matches that of
 --- `:set`: the local value of an option is returned if it exists; otherwise,
---- the global value is returned. Local values always correspond to the
---- current buffer or window, unless "buf" or "win" is set in {opts}.
+--- the global value is returned. Local values always correspond to the current
+--- buffer or window, unless "buf" or "win" is set in {opts}.
 ---
 --- @param name string Option name
 --- @param opts vim.api.keyset.option Optional parameters
----             • scope: One of "global" or "local". Analogous to `:setglobal`
----               and `:setlocal`, respectively.
----             • win: `window-ID`. Used for getting window local options.
----             • buf: Buffer number. Used for getting buffer local options.
----               Implies {scope} is "local".
----             • filetype: `filetype`. Used to get the default option for a
----               specific filetype. Cannot be used with any other option.
----               Note: this will trigger `ftplugin` and all `FileType`
----               autocommands for the corresponding filetype.
---- @return any
+--- - scope: One of "global" or "local". Analogous to
+--- `:setglobal` and `:setlocal`, respectively.
+--- - win: `window-ID`. Used for getting window local options.
+--- - buf: Buffer number. Used for getting buffer local options.
+---        Implies {scope} is "local".
+--- - filetype: `filetype`. Used to get the default option for a
+---   specific filetype. Cannot be used with any other option.
+---   Note: this will trigger `ftplugin` and all `FileType`
+---   autocommands for the corresponding filetype.
+--- @return any # Option value
 function vim.api.nvim_get_option_value(name, opts) end
 
 --- Gets info describing process `pid`.
 ---
 --- @param pid integer
---- @return any
+--- @return any # Map of process properties, or NIL if process not found.
 function vim.api.nvim_get_proc(pid) end
 
 --- Gets the immediate children of process `pid`.
 ---
 --- @param pid integer
---- @return any[]
+--- @return any[] # Array of child process ids, empty if process not found.
 function vim.api.nvim_get_proc_children(pid) end
 
---- Find files in runtime directories
+--- Finds files in runtime directories, in 'runtimepath' order.
 ---
 --- "name" can contain wildcards. For example
---- nvim_get_runtime_file("colors/*.vim", true) will return all color scheme
---- files. Always use forward slashes (/) in the search pattern for
+--- `nvim_get_runtime_file("colors/*.{vim,lua}", true)` will return all color
+--- scheme files. Always use forward slashes (/) in the search pattern for
 --- subdirectories regardless of platform.
 ---
 --- It is not an error to not find any files. An empty array is returned then.
 ---
 --- @param name string pattern of files to search for
 --- @param all boolean whether to return all matches or only the first
---- @return string[]
+--- @return string[] # list of absolute paths to the found files
 function vim.api.nvim_get_runtime_file(name, all) end
 
 --- Gets a global (g:) variable.
 ---
 --- @param name string Variable name
---- @return any
+--- @return any # Variable value
 function vim.api.nvim_get_var(name) end
 
 --- Gets a v: variable.
 ---
 --- @param name string Variable name
---- @return any
+--- @return any # Variable value
 function vim.api.nvim_get_vvar(name) end
 
---- Queues raw user-input. Unlike `nvim_feedkeys()`, this uses a low-level
---- input buffer and the call is non-blocking (input is processed
---- asynchronously by the eventloop).
+--- Queues raw user-input. Unlike `nvim_feedkeys()`, this uses a low-level input buffer and the call
+--- is non-blocking (input is processed asynchronously by the eventloop).
+---
+--- To input blocks of text, `nvim_paste()` is much faster and should be preferred.
 ---
 --- On execution error: does not fail, but updates v:errmsg.
 ---
+--- Note:
+--- |keycodes| like [<CR>] are translated, so "<" is special.
+--- To input a literal "<", send [<LT>].
+---
+--- For mouse events use |nvim_input_mouse()|. The pseudokey form
+--- `<LeftMouse><col,row>` is deprecated since |api-level| 6.
+---
+---
 --- @param keys string to be typed
---- @return integer
+--- @return integer # Number of bytes actually written (can be fewer than
+--- requested if the buffer becomes full).
 function vim.api.nvim_input(keys) end
 
 --- Send mouse event from GUI.
@@ -1508,15 +1578,22 @@ function vim.api.nvim_input(keys) end
 --- Non-blocking: does not wait on any result, but queues the event to be
 --- processed soon by the event loop.
 ---
---- @param button string Mouse button: one of "left", "right", "middle", "wheel",
----               "move", "x1", "x2".
---- @param action string For ordinary buttons, one of "press", "drag", "release". For
----               the wheel, one of "up", "down", "left", "right". Ignored for
----               "move".
---- @param modifier string String of modifiers each represented by a single char. The
----                 same specifiers are used as for a key press, except that
----                 the "-" separator is optional, so "C-A-", "c-a" and "CA"
----                 can all be used to specify Ctrl+Alt+click.
+--- Note:
+--- Currently this doesn't support "scripting" multiple mouse events
+--- by calling it multiple times in a loop: the intermediate mouse
+--- positions will be ignored. It should be used to implement real-time
+--- mouse input in a GUI. The deprecated pseudokey form
+--- (`<LeftMouse><col,row>`) of |nvim_input()| has the same limitation.
+---
+---
+--- @param button string Mouse button: one of "left", "right", "middle", "wheel", "move",
+--- "x1", "x2".
+--- @param action string For ordinary buttons, one of "press", "drag", "release".
+--- For the wheel, one of "up", "down", "left", "right". Ignored for "move".
+--- @param modifier string String of modifiers each represented by a single char.
+--- The same specifiers are used as for a key press, except
+--- that the "-" separator is optional, so "C-A-", "c-a"
+--- and "CA" can all be used to specify Ctrl+Alt+click.
 --- @param grid integer Grid number if the client uses `ui-multigrid`, else 0.
 --- @param row integer Mouse row-position (zero-based, like redraw events)
 --- @param col integer Mouse column-position (zero-based, like redraw events)
@@ -1524,35 +1601,41 @@ function vim.api.nvim_input_mouse(button, action, modifier, grid, row, col) end
 
 --- Gets the current list of buffer handles
 ---
---- Includes unlisted (unloaded/deleted) buffers, like `:ls!`. Use
---- `nvim_buf_is_loaded()` to check if a buffer is loaded.
+--- Includes unlisted (unloaded/deleted) buffers, like `:ls!`.
+--- Use `nvim_buf_is_loaded()` to check if a buffer is loaded.
 ---
---- @return integer[]
+--- @return integer[] # List of buffer handles
 function vim.api.nvim_list_bufs() end
 
 --- Get information about all open channels.
 ---
---- @return any[]
+--- @return any[] # Array of Dictionaries, each describing a channel with
+--- the format specified at |nvim_get_chan_info()|.
 function vim.api.nvim_list_chans() end
 
 --- Gets the paths contained in `runtime-search-path`.
 ---
---- @return string[]
+--- @return string[] # List of paths
 function vim.api.nvim_list_runtime_paths() end
 
 --- Gets the current list of tabpage handles.
 ---
---- @return integer[]
+--- @return integer[] # List of tabpage handles
 function vim.api.nvim_list_tabpages() end
 
 --- Gets a list of dictionaries representing attached UIs.
 ---
---- @return any[]
+--- @return any[] # Array of UI dictionaries, each with these keys:
+--- - "height"  Requested height of the UI
+--- - "width"   Requested width of the UI
+--- - "rgb"     true if the UI uses RGB colors (false implies |cterm-colors|)
+--- - "ext_..." Requested UI extensions, see |ui-option|
+--- - "chan"    |channel-id| of remote UI
 function vim.api.nvim_list_uis() end
 
 --- Gets the current list of window handles.
 ---
---- @return integer[]
+--- @return integer[] # List of window handles
 function vim.api.nvim_list_wins() end
 
 --- Sets the current editor state from the given `context` map.
@@ -1575,210 +1658,194 @@ function vim.api.nvim_notify(msg, log_level, opts) end
 --- Open a terminal instance in a buffer
 ---
 --- By default (and currently the only option) the terminal will not be
---- connected to an external process. Instead, input send on the channel will
---- be echoed directly by the terminal. This is useful to display ANSI
---- terminal sequences returned as part of a rpc message, or similar.
+--- connected to an external process. Instead, input send on the channel
+--- will be echoed directly by the terminal. This is useful to display
+--- ANSI terminal sequences returned as part of a rpc message, or similar.
 ---
 --- Note: to directly initiate the terminal using the right size, display the
 --- buffer in a configured window before calling this. For instance, for a
 --- floating display, first create an empty buffer using `nvim_create_buf()`,
---- then display it using `nvim_open_win()`, and then call this function. Then
---- `nvim_chan_send()` can be called immediately to process sequences in a
---- virtual terminal having the intended size.
+--- then display it using `nvim_open_win()`, and then  call this function.
+--- Then `nvim_chan_send()` can be called immediately to process sequences
+--- in a virtual terminal having the intended size.
 ---
 --- @param buffer integer the buffer to use (expected to be empty)
 --- @param opts vim.api.keyset.open_term Optional parameters.
----             • on_input: Lua callback for input sent, i e keypresses in
----               terminal mode. Note: keypresses are sent raw as they would
----               be to the pty master end. For instance, a carriage return is
----               sent as a "\r", not as a "\n". `textlock` applies. It is
----               possible to call `nvim_chan_send()` directly in the callback
----               however. `["input", term, bufnr, data]`
----             • force_crlf: (boolean, default true) Convert "\n" to "\r\n".
---- @return integer
+--- - on_input: Lua callback for input sent, i e keypresses in terminal
+---   mode. Note: keypresses are sent raw as they would be to the pty
+---   master end. For instance, a carriage return is sent
+---   as a "\r", not as a "\n". `textlock` applies. It is possible
+---   to call `nvim_chan_send()` directly in the callback however.
+---        `["input", term, bufnr, data]`
+--- - force_crlf: (boolean, default true) Convert "\n" to "\r\n".
+--- @return integer # Channel id, or 0 on error
 function vim.api.nvim_open_term(buffer, opts) end
 
 --- Opens a new split window, or a floating window if `relative` is specified,
 --- or an external window (managed by the UI) if `external` is specified.
 ---
 --- Floats are windows that are drawn above the split layout, at some anchor
---- position in some other window. Floats can be drawn internally or by
---- external GUI with the `ui-multigrid` extension. External windows are only
---- supported with multigrid GUIs, and are displayed as separate top-level
---- windows.
+--- position in some other window. Floats can be drawn internally or by external
+--- GUI with the `ui-multigrid` extension. External windows are only supported
+--- with multigrid GUIs, and are displayed as separate top-level windows.
 ---
 --- For a general overview of floats, see `api-floatwin`.
 ---
 --- The `width` and `height` of the new window must be specified when opening
 --- a floating window, but are optional for normal windows.
 ---
---- If `relative` and `external` are omitted, a normal "split" window is
---- created. The `win` property determines which window will be split. If no
---- `win` is provided or `win == 0`, a window will be created adjacent to the
---- current window. If -1 is provided, a top-level split will be created.
---- `vertical` and `split` are only valid for normal windows, and are used to
---- control split direction. For `vertical`, the exact direction is determined
---- by `'splitright'` and `'splitbelow'`. Split windows cannot have
---- `bufpos`/`row`/`col`/`border`/`title`/`footer` properties.
+--- If `relative` and `external` are omitted, a normal "split" window is created.
+--- The `win` property determines which window will be split. If no `win` is
+--- provided or `win == 0`, a window will be created adjacent to the current window.
+--- If -1 is provided, a top-level split will be created. `vertical` and `split` are
+--- only valid for normal windows, and are used to control split direction. For `vertical`,
+--- the exact direction is determined by `'splitright'` and `'splitbelow'`.
+--- Split windows cannot have `bufpos`/`row`/`col`/`border`/`title`/`footer`
+--- properties.
 ---
 --- With relative=editor (row=0,col=0) refers to the top-left corner of the
 --- screen-grid and (row=Lines-1,col=Columns-1) refers to the bottom-right
 --- corner. Fractional values are allowed, but the builtin implementation
 --- (used by non-multigrid UIs) will always round down to nearest integer.
 ---
---- Out-of-bounds values, and configurations that make the float not fit
---- inside the main editor, are allowed. The builtin implementation truncates
---- values so floats are fully within the main screen grid. External GUIs
---- could let floats hover outside of the main window like a tooltip, but this
---- should not be used to specify arbitrary WM screen positions.
+--- Out-of-bounds values, and configurations that make the float not fit inside
+--- the main editor, are allowed. The builtin implementation truncates values
+--- so floats are fully within the main screen grid. External GUIs
+--- could let floats hover outside of the main window like a tooltip, but
+--- this should not be used to specify arbitrary WM screen positions.
 ---
 --- Example (Lua): window-relative float
 ---
 --- ```lua
----     vim.api.nvim_open_win(0, false,
----       {relative='win', row=3, col=3, width=12, height=3})
+--- vim.api.nvim_open_win(0, false,
+---   {relative='win', row=3, col=3, width=12, height=3})
 --- ```
 ---
 --- Example (Lua): buffer-relative float (travels as buffer is scrolled)
 ---
 --- ```lua
----     vim.api.nvim_open_win(0, false,
----       {relative='win', width=12, height=3, bufpos={100,10}})
+--- vim.api.nvim_open_win(0, false,
+---   {relative='win', width=12, height=3, bufpos={100,10}})
 --- ```
 ---
 --- Example (Lua): vertical split left of the current window
 ---
 --- ```lua
----     vim.api.nvim_open_win(0, false, {
----       split = 'left',
----       win = 0
----     })
+--- vim.api.nvim_open_win(0, false, {
+---   split = 'left',
+---   win = 0
+--- })
 --- ```
 ---
----
 --- @param buffer integer Buffer to display, or 0 for current buffer
 --- @param enter boolean Enter the window (make it the current window)
 --- @param config vim.api.keyset.win_config Map defining the window configuration. Keys:
----               • relative: Sets the window layout to "floating", placed at
----                 (row,col) coordinates relative to:
----                 • "editor" The global editor grid
----                 • "win" Window given by the `win` field, or current
----                   window.
----                 • "cursor" Cursor position in current window.
----                 • "mouse" Mouse position
----               • win: `window-ID` window to split, or relative window when
----                 creating a float (relative="win").
----               • anchor: Decides which corner of the float to place at
----                 (row,col):
----                 • "NW" northwest (default)
----                 • "NE" northeast
----                 • "SW" southwest
----                 • "SE" southeast
----               • width: Window width (in character cells). Minimum of 1.
----               • height: Window height (in character cells). Minimum of 1.
----               • bufpos: Places float relative to buffer text (only when
----                 relative="win"). Takes a tuple of zero-indexed
----                 `[line, column]`. `row` and `col` if given are applied
----                 relative to this position, else they default to:
----                 • `row=1` and `col=0` if `anchor` is "NW" or "NE"
----                 • `row=0` and `col=0` if `anchor` is "SW" or "SE" (thus
----                   like a tooltip near the buffer text).
----               • row: Row position in units of "screen cell height", may be
----                 fractional.
----               • col: Column position in units of "screen cell width", may
----                 be fractional.
----               • focusable: Enable focus by user actions (wincmds, mouse
----                 events). Defaults to true. Non-focusable windows can be
----                 entered by `nvim_set_current_win()`.
----               • external: GUI should display the window as an external
----                 top-level window. Currently accepts no other positioning
----                 configuration together with this.
----               • zindex: Stacking order. floats with higher `zindex` go on
----                 top on floats with lower indices. Must be larger than
----                 zero. The following screen elements have hard-coded
----                 z-indices:
----                 • 100: insert completion popupmenu
----                 • 200: message scrollback
----                 • 250: cmdline completion popupmenu (when
----                   wildoptions+=pum) The default value for floats are 50.
----                   In general, values below 100 are recommended, unless
----                   there is a good reason to overshadow builtin elements.
----               • style: (optional) Configure the appearance of the window.
----                 Currently only supports one value:
----                 • "minimal" Nvim will display the window with many UI
----                   options disabled. This is useful when displaying a
----                   temporary float where the text should not be edited.
----                   Disables 'number', 'relativenumber', 'cursorline',
----                   'cursorcolumn', 'foldcolumn', 'spell' and 'list'
----                   options. 'signcolumn' is changed to `auto` and
----                   'colorcolumn' is cleared. 'statuscolumn' is changed to
----                   empty. The end-of-buffer region is hidden by setting
----                   `eob` flag of 'fillchars' to a space char, and clearing
----                   the `hl-EndOfBuffer` region in 'winhighlight'.
----               • border: Style of (optional) window border. This can either
----                 be a string or an array. The string values are
----                 • "none": No border (default).
----                 • "single": A single line box.
----                 • "double": A double line box.
----                 • "rounded": Like "single", but with rounded corners
----                   ("╭" etc.).
----                 • "solid": Adds padding by a single whitespace cell.
----                 • "shadow": A drop shadow effect by blending with the
----                   background.
----                 • If it is an array, it should have a length of eight or
----                   any divisor of eight. The array will specify the eight
----                   chars building up the border in a clockwise fashion
----                   starting with the top-left corner. As an example, the
----                   double box style could be specified as:
---- ```
----                   [ "╔", "═" ,"╗", "║", "╝", "═", "╚", "║" ].
---- ```
----
----                   If the number of chars are less than eight, they will be
----                   repeated. Thus an ASCII border could be specified as
---- ```
----                   [ "/", "-", \"\\\\\", "|" ],
---- ```
----
----                   or all chars the same as
---- ```
----                   [ "x" ].
---- ```
----
----                 An empty string can be used to turn off a specific border,
----                 for instance,
---- ```
----                  [ "", "", "", ">", "", "", "", "<" ]
---- ```
----
----                 will only make vertical borders but not horizontal ones.
----                 By default, `FloatBorder` highlight is used, which links
----                 to `WinSeparator` when not defined. It could also be
----                 specified by character:
---- ```
----                  [ ["+", "MyCorner"], ["x", "MyBorder"] ].
---- ```
----
----               • title: Title (optional) in window border, string or list.
----                 List should consist of `[text, highlight]` tuples. If
----                 string, the default highlight group is `FloatTitle`.
----               • title_pos: Title position. Must be set with `title`
----                 option. Value can be one of "left", "center", or "right".
----                 Default is `"left"`.
----               • footer: Footer (optional) in window border, string or
----                 list. List should consist of `[text, highlight]` tuples.
----                 If string, the default highlight group is `FloatFooter`.
----               • footer_pos: Footer position. Must be set with `footer`
----                 option. Value can be one of "left", "center", or "right".
----                 Default is `"left"`.
----               • noautocmd: If true then all autocommands are blocked for
----                 the duration of the call.
----               • fixed: If true when anchor is NW or SW, the float window
----                 would be kept fixed even if the window would be truncated.
----               • hide: If true the floating window will be hidden.
----               • vertical: Split vertically `:vertical`.
----               • split: Split direction: "left", "right", "above", "below".
---- @return integer
+--- - relative: Sets the window layout to "floating", placed at (row,col)
+---               coordinates relative to:
+---    - "editor" The global editor grid
+---    - "win"    Window given by the `win` field, or current window.
+---    - "cursor" Cursor position in current window.
+---    - "mouse"  Mouse position
+--- - win: `window-ID` window to split, or relative window when creating a
+---    float (relative="win").
+--- - anchor: Decides which corner of the float to place at (row,col):
+---    - "NW" northwest (default)
+---    - "NE" northeast
+---    - "SW" southwest
+---    - "SE" southeast
+--- - width: Window width (in character cells). Minimum of 1.
+--- - height: Window height (in character cells). Minimum of 1.
+--- - bufpos: Places float relative to buffer text (only when
+---     relative="win"). Takes a tuple of zero-indexed `[line, column]`.
+---     `row` and `col` if given are applied relative to this
+---     position, else they default to:
+---     - `row=1` and `col=0` if `anchor` is "NW" or "NE"
+---     - `row=0` and `col=0` if `anchor` is "SW" or "SE"
+---       (thus like a tooltip near the buffer text).
+--- - row: Row position in units of "screen cell height", may be fractional.
+--- - col: Column position in units of "screen cell width", may be
+---          fractional.
+--- - focusable: Enable focus by user actions (wincmds, mouse events).
+---     Defaults to true. Non-focusable windows can be entered by
+---     `nvim_set_current_win()`.
+--- - external: GUI should display the window as an external
+---     top-level window. Currently accepts no other positioning
+---     configuration together with this.
+--- - zindex: Stacking order. floats with higher `zindex` go on top on
+---             floats with lower indices. Must be larger than zero. The
+---             following screen elements have hard-coded z-indices:
+---     - 100: insert completion popupmenu
+---     - 200: message scrollback
+---     - 250: cmdline completion popupmenu (when wildoptions+=pum)
+---   The default value for floats are 50.  In general, values below 100 are
+---   recommended, unless there is a good reason to overshadow builtin
+---   elements.
+--- - style: (optional) Configure the appearance of the window. Currently
+---     only supports one value:
+---     - "minimal"  Nvim will display the window with many UI options
+---                  disabled. This is useful when displaying a temporary
+---                  float where the text should not be edited. Disables
+---                  'number', 'relativenumber', 'cursorline', 'cursorcolumn',
+---                  'foldcolumn', 'spell' and 'list' options. 'signcolumn'
+---                  is changed to `auto` and 'colorcolumn' is cleared.
+---                  'statuscolumn' is changed to empty. The end-of-buffer
+---                   region is hidden by setting `eob` flag of
+---                  'fillchars' to a space char, and clearing the
+---                  `hl-EndOfBuffer` region in 'winhighlight'.
+--- - border: Style of (optional) window border. This can either be a string
+---   or an array. The string values are
+---   - "none": No border (default).
+---   - "single": A single line box.
+---   - "double": A double line box.
+---   - "rounded": Like "single", but with rounded corners ("╭" etc.).
+---   - "solid": Adds padding by a single whitespace cell.
+---   - "shadow": A drop shadow effect by blending with the background.
+---   - If it is an array, it should have a length of eight or any divisor of
+---     eight. The array will specify the eight chars building up the border
+---     in a clockwise fashion starting with the top-left corner. As an
+---     example, the double box style could be specified as:
+---     ```
+---     [ "╔", "═" ,"╗", "║", "╝", "═", "╚", "║" ].
+---     ```
+---     If the number of chars are less than eight, they will be repeated. Thus
+---     an ASCII border could be specified as
+---     ```
+---     [ "/", "-", \"\\\\\", "|" ],
+---     ```
+---     or all chars the same as
+---     ```
+---     [ "x" ].
+---     ```
+---   An empty string can be used to turn off a specific border, for instance,
+---   ```
+---     [ "", "", "", ">", "", "", "", "<" ]
+---   ```
+---   will only make vertical borders but not horizontal ones.
+---   By default, `FloatBorder` highlight is used, which links to `WinSeparator`
+---   when not defined.  It could also be specified by character:
+---   ```
+---     [ ["+", "MyCorner"], ["x", "MyBorder"] ].
+---   ```
+--- - title: Title (optional) in window border, string or list.
+---   List should consist of `[text, highlight]` tuples.
+---   If string, or a tuple lacks a highlight, the default highlight group is `FloatTitle`.
+--- - title_pos: Title position. Must be set with `title` option.
+---   Value can be one of "left", "center", or "right".
+---   Default is `"left"`.
+--- - footer: Footer (optional) in window border, string or list.
+---   List should consist of `[text, highlight]` tuples.
+---   If string, or a tuple lacks a highlight, the default highlight group is `FloatFooter`.
+--- - footer_pos: Footer position. Must be set with `footer` option.
+---   Value can be one of "left", "center", or "right".
+---   Default is `"left"`.
+--- - noautocmd: If true then all autocommands are blocked for the duration of
+---   the call.
+--- - fixed: If true when anchor is NW or SW, the float window
+---          would be kept fixed even if the window would be truncated.
+--- - hide: If true the floating window will be hidden.
+--- - vertical: Split vertically `:vertical`.
+--- - split: Split direction: "left", "right", "above", "below".
+--- @return integer # Window handle, or 0 on error
 function vim.api.nvim_open_win(buffer, enter, config) end
 
 --- Writes a message to the Vim output buffer. Does not append "\n", the
@@ -1793,92 +1860,207 @@ function vim.api.nvim_out_write(str) end
 ---
 --- @param str string Command line string to parse. Cannot contain "\n".
 --- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use.
---- @return vim.api.keyset.parse_cmd
+--- @return vim.api.keyset.parse_cmd # Dict containing command information, with these keys:
+--- - cmd: (string) Command name.
+--- - range: (array) (optional) Command range ([<line1>] [<line2>]).
+---                  Omitted if command doesn't accept a range.
+---                  Otherwise, has no elements if no range was specified, one element if
+---                  only a single range item was specified, or two elements if both range
+---                  items were specified.
+--- - count: (number) (optional) Command [<count>].
+---                   Omitted if command cannot take a count.
+--- - reg: (string) (optional) Command [<register>].
+---                 Omitted if command cannot take a register.
+--- - bang: (boolean) Whether command contains a [<bang>] (!) modifier.
+--- - args: (array) Command arguments.
+--- - addr: (string) Value of |:command-addr|. Uses short name or "line" for -addr=lines.
+--- - nargs: (string) Value of |:command-nargs|.
+--- - nextcmd: (string) Next command if there are multiple commands separated by a |:bar|.
+---                     Empty if there isn't a next command.
+--- - magic: (dict) Which characters have special meaning in the command arguments.
+---     - file: (boolean) The command expands filenames. Which means characters such as "%",
+---                       "#" and wildcards are expanded.
+---     - bar: (boolean) The "|" character is treated as a command separator and the double
+---                      quote character (") is treated as the start of a comment.
+--- - mods: (dict) |:command-modifiers|.
+---     - filter: (dict) |:filter|.
+---         - pattern: (string) Filter pattern. Empty string if there is no filter.
+---         - force: (boolean) Whether filter is inverted or not.
+---     - silent: (boolean) |:silent|.
+---     - emsg_silent: (boolean) |:silent!|.
+---     - unsilent: (boolean) |:unsilent|.
+---     - sandbox: (boolean) |:sandbox|.
+---     - noautocmd: (boolean) |:noautocmd|.
+---     - browse: (boolean) |:browse|.
+---     - confirm: (boolean) |:confirm|.
+---     - hide: (boolean) |:hide|.
+---     - horizontal: (boolean) |:horizontal|.
+---     - keepalt: (boolean) |:keepalt|.
+---     - keepjumps: (boolean) |:keepjumps|.
+---     - keepmarks: (boolean) |:keepmarks|.
+---     - keeppatterns: (boolean) |:keeppatterns|.
+---     - lockmarks: (boolean) |:lockmarks|.
+---     - noswapfile: (boolean) |:noswapfile|.
+---     - tab: (integer) |:tab|. -1 when omitted.
+---     - verbose: (integer) |:verbose|. -1 when omitted.
+---     - vertical: (boolean) |:vertical|.
+---     - split: (string) Split modifier string, is an empty string when there's no split
+---                       modifier. If there is a split modifier it can be one of:
+---       - "aboveleft": |:aboveleft|.
+---       - "belowright": |:belowright|.
+---       - "topleft": |:topleft|.
+---       - "botright": |:botright|.
 function vim.api.nvim_parse_cmd(str, opts) end
 
 --- Parse a Vimscript expression.
 ---
 --- @param expr string Expression to parse. Always treated as a single line.
 --- @param flags string Flags:
----              • "m" if multiple expressions in a row are allowed (only the
----                first one will be parsed),
----              • "E" if EOC tokens are not allowed (determines whether they
----                will stop parsing process or be recognized as an
----                operator/space, though also yielding an error).
----              • "l" when needing to start parsing with lvalues for ":let"
----                or ":for". Common flag sets:
----              • "m" to parse like for `":echo"`.
----              • "E" to parse like for `"<C-r>="`.
----              • empty string for ":call".
----              • "lm" to parse for ":let".
---- @param highlight boolean If true, return value will also include "highlight" key
----                  containing array of 4-tuples (arrays) (Integer, Integer,
----                  Integer, String), where first three numbers define the
----                  highlighted region and represent line, starting column
----                  and ending column (latter exclusive: one should highlight
----                  region [start_col, end_col)).
---- @return table<string,any>
+--- - "m" if multiple expressions in a row are allowed (only
+---   the first one will be parsed),
+--- - "E" if EOC tokens are not allowed (determines whether
+---   they will stop parsing process or be recognized as an
+---   operator/space, though also yielding an error).
+--- - "l" when needing to start parsing with lvalues for
+---   ":let" or ":for".
+--- Common flag sets:
+--- - "m" to parse like for `":echo"`.
+--- - "E" to parse like for `"<C-r>="`.
+--- - empty string for ":call".
+--- - "lm" to parse for ":let".
+--- @param highlight boolean If true, return value will also include "highlight"
+--- key containing array of 4-tuples (arrays) (Integer,
+--- Integer, Integer, String), where first three numbers
+--- define the highlighted region and represent line,
+--- starting column and ending column (latter exclusive:
+--- one should highlight region [start_col, end_col)).
+--- @return table<string,any> #
+--- - AST: top-level dict with these keys:
+---   - "error": Dict with error, present only if parser saw some
+---            error. Contains the following keys:
+---     - "message": String, error message in printf format, translated.
+---                  Must contain exactly one "%.*s".
+---     - "arg": String, error message argument.
+---   - "len": Amount of bytes successfully parsed. With flags equal to ""
+---            that should be equal to the length of expr string.
+---            ("Successfully parsed" here means "participated in AST
+---             creation", not "till the first error".)
+---   - "ast": AST, either nil or a dict with these keys:
+---     - "type": node type, one of the value names from ExprASTNodeType
+---               stringified without "kExprNode" prefix.
+---     - "start": a pair `[line, column]` describing where node is "started"
+---                where "line" is always 0 (will not be 0 if you will be
+---                using this API on e.g. ":let", but that is not
+---                present yet). Both elements are Integers.
+---     - "len": “length” of the node. This and "start" are there for
+---              debugging purposes primary (debugging parser and providing
+---              debug information).
+---     - "children": a list of nodes described in top/"ast". There always
+---                   is zero, one or two children, key will not be present
+---                   if node has no children. Maximum number of children
+---                   may be found in node_maxchildren array.
+--- - Local values (present only for certain nodes):
+---   - "scope": a single Integer, specifies scope for "Option" and
+---              "PlainIdentifier" nodes. For "Option" it is one of
+---              ExprOptScope values, for "PlainIdentifier" it is one of
+---              ExprVarScope values.
+---   - "ident": identifier (without scope, if any), present for "Option",
+---              "PlainIdentifier", "PlainKey" and "Environment" nodes.
+---   - "name": Integer, register name (one character) or -1. Only present
+---           for "Register" nodes.
+---   - "cmp_type": String, comparison type, one of the value names from
+---                 ExprComparisonType, stringified without "kExprCmp"
+---                 prefix. Only present for "Comparison" nodes.
+---   - "ccs_strategy": String, case comparison strategy, one of the
+---                     value names from ExprCaseCompareStrategy,
+---                     stringified without "kCCStrategy" prefix. Only
+---                     present for "Comparison" nodes.
+---   - "augmentation": String, augmentation type for "Assignment" nodes.
+---                     Is either an empty string, "Add", "Subtract" or
+---                     "Concat" for "=", "+=", "-=" or ".=" respectively.
+---   - "invert": Boolean, true if result of comparison needs to be
+---               inverted. Only present for "Comparison" nodes.
+---   - "ivalue": Integer, integer value for "Integer" nodes.
+---   - "fvalue": Float, floating-point value for "Float" nodes.
+---   - "svalue": String, value for "SingleQuotedString" and
+---               "DoubleQuotedString" nodes.
 function vim.api.nvim_parse_expression(expr, flags, highlight) end
 
---- Pastes at cursor, in any mode.
+--- Pastes at cursor (in any mode), and sets "redo" so dot (`.`) will repeat the input. UIs call
+--- this to implement "paste", but it's also intended for use by scripts to input large,
+--- dot-repeatable blocks of text (as opposed to `nvim_input()` which is subject to mappings/events
+--- and is thus much slower).
+---
+--- Invokes the `vim.paste()` handler, which handles each mode appropriately.
 ---
---- Invokes the `vim.paste` handler, which handles each mode appropriately.
---- Sets redo/undo. Faster than `nvim_input()`. Lines break at LF ("\n").
+--- Errors ('nomodifiable', `vim.paste()` failure, …) are reflected in `err` but do not affect the
+--- return value (which is strictly decided by `vim.paste()`).  On error or cancel, subsequent calls
+--- are ignored ("drained") until the next paste is initiated (phase 1 or -1).
 ---
---- Errors ('nomodifiable', `vim.paste()` failure, …) are reflected in `err`
---- but do not affect the return value (which is strictly decided by
---- `vim.paste()`). On error, subsequent calls are ignored ("drained") until
---- the next paste is initiated (phase 1 or -1).
+--- Useful in mappings and scripts to insert multiline text. Example:
 ---
---- @param data string Multiline input. May be binary (containing NUL bytes).
+--- ```lua
+--- vim.keymap.set('n', 'x', function()
+---   vim.api.nvim_paste([[
+---     line1
+---     line2
+---     line3
+---   ]], false, -1)
+--- end, { buffer = true })
+--- ```
+---
+--- @param data string Multiline input. Lines break at LF ("\n"). May be binary (containing NUL bytes).
 --- @param crlf boolean Also break lines at CR and CRLF.
---- @param phase integer -1: paste in a single call (i.e. without streaming). To
----              "stream" a paste, call `nvim_paste` sequentially with these
----              `phase` values:
----              • 1: starts the paste (exactly once)
----              • 2: continues the paste (zero or more times)
----              • 3: ends the paste (exactly once)
---- @return boolean
+--- @param phase integer -1: paste in a single call (i.e. without streaming).
+--- To "stream" a paste, call `nvim_paste` sequentially with
+--- these `phase` values:
+---   - 1: starts the paste (exactly once)
+---   - 2: continues the paste (zero or more times)
+---   - 3: ends the paste (exactly once)
+--- @return boolean #
+--- - true: Client may continue pasting.
+--- - false: Client should cancel the paste.
 function vim.api.nvim_paste(data, crlf, phase) end
 
---- Puts text at cursor, in any mode.
+--- Puts text at cursor, in any mode. For dot-repeatable input, use `nvim_paste()`.
 ---
 --- Compare `:put` and `p` which are always linewise.
 ---
 --- @param lines string[] `readfile()`-style list of lines. `channel-lines`
 --- @param type string Edit behavior: any `getregtype()` result, or:
----             • "b" `blockwise-visual` mode (may include width, e.g. "b3")
----             • "c" `charwise` mode
----             • "l" `linewise` mode
----             • "" guess by contents, see `setreg()`
+--- - "b" `blockwise-visual` mode (may include width, e.g. "b3")
+--- - "c" `charwise` mode
+--- - "l" `linewise` mode
+--- - ""  guess by contents, see `setreg()`
 --- @param after boolean If true insert after cursor (like `p`), or before (like `P`).
 --- @param follow boolean If true place cursor at end of inserted text.
 function vim.api.nvim_put(lines, type, after, follow) end
 
---- Replaces terminal codes and `keycodes` (<CR>, <Esc>, ...) in a string with
+--- Replaces terminal codes and `keycodes` ([<CR>], [<Esc>], ...) in a string with
 --- the internal representation.
 ---
+--- @see replace_termcodes
+--- @see cpoptions
 --- @param str string String to be converted.
 --- @param from_part boolean Legacy Vim parameter. Usually true.
---- @param do_lt boolean Also translate <lt>. Ignored if `special` is false.
---- @param special boolean Replace `keycodes`, e.g. <CR> becomes a "\r" char.
+--- @param do_lt boolean Also translate [<lt>]. Ignored if `special` is false.
+--- @param special boolean Replace `keycodes`, e.g. [<CR>] becomes a "\r" char.
 --- @return string
 function vim.api.nvim_replace_termcodes(str, from_part, do_lt, special) end
 
 --- Selects an item in the completion popup menu.
 ---
 --- If neither `ins-completion` nor `cmdline-completion` popup menu is active
---- this API call is silently ignored. Useful for an external UI using
---- `ui-popupmenu` to control the popup menu with the mouse. Can also be used
---- in a mapping; use <Cmd> `:map-cmd` or a Lua mapping to ensure the mapping
+--- this API call is silently ignored.
+--- Useful for an external UI using `ui-popupmenu` to control the popup menu with the mouse.
+--- Can also be used in a mapping; use [<Cmd>] `:map-cmd` or a Lua mapping to ensure the mapping
 --- doesn't end completion mode.
 ---
---- @param item integer Index (zero-based) of the item to select. Value of -1 selects
----             nothing and restores the original text.
---- @param insert boolean For `ins-completion`, whether the selection should be
----               inserted in the buffer. Ignored for `cmdline-completion`.
---- @param finish boolean Finish the completion and dismiss the popup menu. Implies
----               {insert}.
+--- @param item integer Index (zero-based) of the item to select. Value of -1 selects nothing
+--- and restores the original text.
+--- @param insert boolean For `ins-completion`, whether the selection should be inserted in the buffer.
+--- Ignored for `cmdline-completion`.
+--- @param finish boolean Finish the completion and dismiss the popup menu. Implies {insert}.
 --- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use.
 function vim.api.nvim_select_popupmenu_item(item, insert, finish, opts) end
 
@@ -1909,111 +2091,118 @@ function vim.api.nvim_set_current_win(window) end
 
 --- Set or change decoration provider for a `namespace`
 ---
---- This is a very general purpose interface for having Lua callbacks being
---- triggered during the redraw code.
+--- This is a very general purpose interface for having Lua callbacks
+--- being triggered during the redraw code.
 ---
---- The expected usage is to set `extmarks` for the currently redrawn buffer.
---- `nvim_buf_set_extmark()` can be called to add marks on a per-window or
---- per-lines basis. Use the `ephemeral` key to only use the mark for the
---- current screen redraw (the callback will be called again for the next
---- redraw).
+--- The expected usage is to set `extmarks` for the currently
+--- redrawn buffer. `nvim_buf_set_extmark()` can be called to add marks
+--- on a per-window or per-lines basis. Use the `ephemeral` key to only
+--- use the mark for the current screen redraw (the callback will be called
+--- again for the next redraw).
 ---
 --- Note: this function should not be called often. Rather, the callbacks
 --- themselves can be used to throttle unneeded callbacks. the `on_start`
 --- callback can return `false` to disable the provider until the next redraw.
---- Similarly, return `false` in `on_win` will skip the `on_lines` calls for
---- that window (but any extmarks set in `on_win` will still be used). A
---- plugin managing multiple sources of decoration should ideally only set one
---- provider, and merge the sources internally. You can use multiple `ns_id`
+--- Similarly, return `false` in `on_win` will skip the `on_line` calls
+--- for that window (but any extmarks set in `on_win` will still be used).
+--- A plugin managing multiple sources of decoration should ideally only set
+--- one provider, and merge the sources internally. You can use multiple `ns_id`
 --- for the extmarks set/modified inside the callback anyway.
 ---
---- Note: doing anything other than setting extmarks is considered
---- experimental. Doing things like changing options are not explicitly
---- forbidden, but is likely to have unexpected consequences (such as 100% CPU
---- consumption). doing `vim.rpcnotify` should be OK, but `vim.rpcrequest` is
---- quite dubious for the moment.
+--- Note: doing anything other than setting extmarks is considered experimental.
+--- Doing things like changing options are not explicitly forbidden, but is
+--- likely to have unexpected consequences (such as 100% CPU consumption).
+--- Doing `vim.rpcnotify` should be OK, but `vim.rpcrequest` is quite dubious
+--- for the moment.
 ---
---- Note: It is not allowed to remove or update extmarks in 'on_line'
---- callbacks.
+--- Note: It is not allowed to remove or update extmarks in `on_line` callbacks.
 ---
 --- @param ns_id integer Namespace id from `nvim_create_namespace()`
 --- @param opts vim.api.keyset.set_decoration_provider Table of callbacks:
----             • on_start: called first on each screen redraw
---- ```
----                ["start", tick]
---- ```
+--- - on_start: called first on each screen redraw
+---   ```
+---     ["start", tick]
+---   ```
+--- - on_buf: called for each buffer being redrawn (before
+---   window callbacks)
+---   ```
+---     ["buf", bufnr, tick]
+---   ```
+--- - on_win: called when starting to redraw a specific window.
+---   ```
+---     ["win", winid, bufnr, toprow, botrow]
+---   ```
+--- - on_line: called for each buffer line being redrawn.
+---     (The interaction with fold lines is subject to change)
+---   ```
+---     ["line", winid, bufnr, row]
+---   ```
+--- - on_end: called at the end of a redraw cycle
+---   ```
+---     ["end", tick]
+---   ```
+function vim.api.nvim_set_decoration_provider(ns_id, opts) end
+
+--- Sets a highlight group.
 ---
----             • on_buf: called for each buffer being redrawn (before window
----               callbacks)
---- ```
----                ["buf", bufnr, tick]
---- ```
+--- Note:
+--- Unlike the `:highlight` command which can update a highlight group,
+--- this function completely replaces the definition. For example:
+--- `nvim_set_hl(0, 'Visual', {})` will clear the highlight group
+--- 'Visual'.
 ---
----             • on_win: called when starting to redraw a specific window.
---- ```
----                ["win", winid, bufnr, topline, botline]
---- ```
+--- The fg and bg keys also accept the string values `"fg"` or `"bg"`
+--- which act as aliases to the corresponding foreground and background
+--- values of the Normal group. If the Normal group has not been defined,
+--- using these values results in an error.
 ---
----             • on_line: called for each buffer line being redrawn. (The
----               interaction with fold lines is subject to change)
---- ```
----                ["line", winid, bufnr, row]
---- ```
 ---
----             • on_end: called at the end of a redraw cycle
---- ```
----                ["end", tick]
---- ```
-function vim.api.nvim_set_decoration_provider(ns_id, opts) end
-
---- Sets a highlight group.
+--- If `link` is used in combination with other attributes; only the
+--- `link` will take effect (see |:hi-link|).
+---
 ---
 --- @param ns_id integer Namespace id for this highlight `nvim_create_namespace()`.
----              Use 0 to set a highlight group globally `:highlight`.
----              Highlights from non-global namespaces are not active by
----              default, use `nvim_set_hl_ns()` or `nvim_win_set_hl_ns()` to
----              activate them.
+--- Use 0 to set a highlight group globally `:highlight`.
+--- Highlights from non-global namespaces are not active by default, use
+--- `nvim_set_hl_ns()` or `nvim_win_set_hl_ns()` to activate them.
 --- @param name string Highlight group name, e.g. "ErrorMsg"
 --- @param val vim.api.keyset.highlight Highlight definition map, accepts the following keys:
----            • fg: color name or "#RRGGBB", see note.
----            • bg: color name or "#RRGGBB", see note.
----            • sp: color name or "#RRGGBB"
----            • blend: integer between 0 and 100
----            • bold: boolean
----            • standout: boolean
----            • underline: boolean
----            • undercurl: boolean
----            • underdouble: boolean
----            • underdotted: boolean
----            • underdashed: boolean
----            • strikethrough: boolean
----            • italic: boolean
----            • reverse: boolean
----            • nocombine: boolean
----            • link: name of another highlight group to link to, see
----              `:hi-link`.
----            • default: Don't override existing definition `:hi-default`
----            • ctermfg: Sets foreground of cterm color `ctermfg`
----            • ctermbg: Sets background of cterm color `ctermbg`
----            • cterm: cterm attribute map, like `highlight-args`. If not
----              set, cterm attributes will match those from the attribute map
----              documented above.
----            • force: if true force update the highlight group when it
----              exists.
+--- - fg: color name or "#RRGGBB", see note.
+--- - bg: color name or "#RRGGBB", see note.
+--- - sp: color name or "#RRGGBB"
+--- - blend: integer between 0 and 100
+--- - bold: boolean
+--- - standout: boolean
+--- - underline: boolean
+--- - undercurl: boolean
+--- - underdouble: boolean
+--- - underdotted: boolean
+--- - underdashed: boolean
+--- - strikethrough: boolean
+--- - italic: boolean
+--- - reverse: boolean
+--- - nocombine: boolean
+--- - link: name of another highlight group to link to, see `:hi-link`.
+--- - default: Don't override existing definition `:hi-default`
+--- - ctermfg: Sets foreground of cterm color `ctermfg`
+--- - ctermbg: Sets background of cterm color `ctermbg`
+--- - cterm: cterm attribute map, like `highlight-args`. If not set,
+---          cterm attributes will match those from the attribute map
+---          documented above.
+--- - force: if true force update the highlight group when it exists.
 function vim.api.nvim_set_hl(ns_id, name, val) end
 
---- Set active namespace for highlights defined with `nvim_set_hl()`. This can
---- be set for a single window, see `nvim_win_set_hl_ns()`.
+--- Set active namespace for highlights defined with `nvim_set_hl()`. This can be set for
+--- a single window, see `nvim_win_set_hl_ns()`.
 ---
 --- @param ns_id integer the namespace to use
 function vim.api.nvim_set_hl_ns(ns_id) end
 
---- Set active namespace for highlights defined with `nvim_set_hl()` while
---- redrawing.
+--- Set active namespace for highlights defined with `nvim_set_hl()` while redrawing.
 ---
 --- This function meant to be called while redrawing, primarily from
---- `nvim_set_decoration_provider()` on_win and on_line callbacks, which are
---- allowed to change the namespace during a redraw cycle.
+--- `nvim_set_decoration_provider()` on_win and on_line callbacks, which
+--- are allowed to change the namespace during a redraw cycle.
 ---
 --- @param ns_id integer the namespace to activate
 function vim.api.nvim_set_hl_ns_fast(ns_id) end
@@ -2022,37 +2211,34 @@ function vim.api.nvim_set_hl_ns_fast(ns_id) end
 ---
 --- To set a buffer-local mapping, use `nvim_buf_set_keymap()`.
 ---
---- Unlike `:map`, leading/trailing whitespace is accepted as part of the
---- {lhs} or {rhs}. Empty {rhs} is <Nop>. `keycodes` are replaced as usual.
+--- Unlike `:map`, leading/trailing whitespace is accepted as part of the {lhs} or {rhs}.
+--- Empty {rhs} is [<Nop>]. `keycodes` are replaced as usual.
 ---
 --- Example:
 ---
 --- ```vim
----     call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true})
+--- call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true})
 --- ```
 ---
 --- is equivalent to:
 ---
 --- ```vim
----     nmap <nowait> <Space><NL> <Nop>
+--- nmap <nowait> <Space><NL> <Nop>
 --- ```
 ---
----
 --- @param mode string Mode short-name (map command prefix: "n", "i", "v", "x", …)
----             or "!" for `:map!`, or empty string for `:map`. "ia", "ca" or
----             "!a" for abbreviation in Insert mode, Cmdline mode, or both,
----             respectively
+--- or "!" for `:map!`, or empty string for `:map`.
+--- "ia", "ca" or "!a" for abbreviation in Insert mode, Cmdline mode, or both, respectively
 --- @param lhs string Left-hand-side `{lhs}` of the mapping.
 --- @param rhs string Right-hand-side `{rhs}` of the mapping.
---- @param opts vim.api.keyset.keymap Optional parameters map: Accepts all `:map-arguments` as keys
----             except <buffer>, values are booleans (default false). Also:
----             • "noremap" disables `recursive_mapping`, like `:noremap`
----             • "desc" human-readable description.
----             • "callback" Lua function called in place of {rhs}.
----             • "replace_keycodes" (boolean) When "expr" is true, replace
----               keycodes in the resulting string (see
----               `nvim_replace_termcodes()`). Returning nil from the Lua
----               "callback" is equivalent to returning an empty string.
+--- @param opts vim.api.keyset.keymap Optional parameters map: Accepts all `:map-arguments` as keys except [<buffer>],
+--- values are booleans (default false). Also:
+--- - "noremap" disables `recursive_mapping`, like `:noremap`
+--- - "desc" human-readable description.
+--- - "callback" Lua function called in place of {rhs}.
+--- - "replace_keycodes" (boolean) When "expr" is true, replace keycodes in the
+---   resulting string (see `nvim_replace_termcodes()`). Returning nil from the Lua
+---   "callback" is equivalent to returning an empty string.
 function vim.api.nvim_set_keymap(mode, lhs, rhs, opts) end
 
 --- @deprecated
@@ -2069,10 +2255,10 @@ function vim.api.nvim_set_option(name, value) end
 --- @param name string Option name
 --- @param value any New option value
 --- @param opts vim.api.keyset.option Optional parameters
----             • scope: One of "global" or "local". Analogous to `:setglobal`
----               and `:setlocal`, respectively.
----             • win: `window-ID`. Used for setting window local option.
----             • buf: Buffer number. Used for setting buffer local option.
+--- - scope: One of "global" or "local". Analogous to
+--- `:setglobal` and `:setlocal`, respectively.
+--- - win: `window-ID`. Used for setting window local option.
+--- - buf: Buffer number. Used for setting buffer local option.
 function vim.api.nvim_set_option_value(name, value, opts) end
 
 --- Sets a global (g:) variable.
@@ -2087,11 +2273,11 @@ function vim.api.nvim_set_var(name, value) end
 --- @param value any Variable value
 function vim.api.nvim_set_vvar(name, value) end
 
---- Calculates the number of display cells occupied by `text`. Control
---- characters including <Tab> count as one cell.
+--- Calculates the number of display cells occupied by `text`.
+--- Control characters including [<Tab>] count as one cell.
 ---
 --- @param text string Some text
---- @return integer
+--- @return integer # Number of cells
 function vim.api.nvim_strwidth(text) end
 
 --- Removes a tab-scoped (t:) variable
@@ -2103,32 +2289,32 @@ function vim.api.nvim_tabpage_del_var(tabpage, name) end
 --- Gets the tabpage number
 ---
 --- @param tabpage integer Tabpage handle, or 0 for current tabpage
---- @return integer
+--- @return integer # Tabpage number
 function vim.api.nvim_tabpage_get_number(tabpage) end
 
 --- Gets a tab-scoped (t:) variable
 ---
 --- @param tabpage integer Tabpage handle, or 0 for current tabpage
 --- @param name string Variable name
---- @return any
+--- @return any # Variable value
 function vim.api.nvim_tabpage_get_var(tabpage, name) end
 
 --- Gets the current window in a tabpage
 ---
 --- @param tabpage integer Tabpage handle, or 0 for current tabpage
---- @return integer
+--- @return integer # Window handle
 function vim.api.nvim_tabpage_get_win(tabpage) end
 
 --- Checks if a tabpage is valid
 ---
 --- @param tabpage integer Tabpage handle, or 0 for current tabpage
---- @return boolean
+--- @return boolean # true if the tabpage is valid, false otherwise
 function vim.api.nvim_tabpage_is_valid(tabpage) end
 
 --- Gets the windows in a tabpage
 ---
 --- @param tabpage integer Tabpage handle, or 0 for current tabpage
---- @return integer[]
+--- @return integer[] # List of windows in `tabpage`
 function vim.api.nvim_tabpage_list_wins(tabpage) end
 
 --- Sets a tab-scoped (t:) variable
@@ -2146,18 +2332,21 @@ function vim.api.nvim_tabpage_set_win(tabpage, win) end
 
 --- Calls a function with window as temporary current window.
 ---
+---
+--- @see `:help win_execute()`
+--- @see vim.api.nvim_buf_call
 --- @param window integer Window handle, or 0 for current window
 --- @param fun function Function to call inside the window (currently Lua callable
----            only)
---- @return any
+--- only)
+--- @return any # Return value of function.
 function vim.api.nvim_win_call(window, fun) end
 
 --- Closes the window (like `:close` with a `window-ID`).
 ---
 --- @param window integer Window handle, or 0 for current window
 --- @param force boolean Behave like `:close!` The last window of a buffer with
----              unwritten changes can be closed. The buffer will become
----              hidden, even if 'hidden' is not set.
+--- unwritten changes can be closed. The buffer will become
+--- hidden, even if 'hidden' is not set.
 function vim.api.nvim_win_close(window, force) end
 
 --- Removes a window-scoped (w:) variable
@@ -2169,7 +2358,7 @@ function vim.api.nvim_win_del_var(window, name) end
 --- Gets the current buffer in a window
 ---
 --- @param window integer Window handle, or 0 for current window
---- @return integer
+--- @return integer # Buffer handle
 function vim.api.nvim_win_get_buf(window) end
 
 --- Gets window configuration.
@@ -2179,27 +2368,29 @@ function vim.api.nvim_win_get_buf(window) end
 --- `relative` is empty for normal windows.
 ---
 --- @param window integer Window handle, or 0 for current window
---- @return vim.api.keyset.win_config
+--- @return vim.api.keyset.win_config # Map defining the window configuration, see |nvim_open_win()|
 function vim.api.nvim_win_get_config(window) end
 
 --- Gets the (1,0)-indexed, buffer-relative cursor position for a given window
 --- (different windows showing the same buffer have independent cursor
 --- positions). `api-indexing`
 ---
+---
+--- @see `:help getcurpos()`
 --- @param window integer Window handle, or 0 for current window
---- @return integer[]
+--- @return integer[] # (row, col) tuple
 function vim.api.nvim_win_get_cursor(window) end
 
 --- Gets the window height
 ---
 --- @param window integer Window handle, or 0 for current window
---- @return integer
+--- @return integer # Height as a count of rows
 function vim.api.nvim_win_get_height(window) end
 
 --- Gets the window number
 ---
 --- @param window integer Window handle, or 0 for current window
---- @return integer
+--- @return integer # Window number
 function vim.api.nvim_win_get_number(window) end
 
 --- @deprecated
@@ -2211,34 +2402,34 @@ function vim.api.nvim_win_get_option(window, name) end
 --- Gets the window position in display cells. First position is zero.
 ---
 --- @param window integer Window handle, or 0 for current window
---- @return integer[]
+--- @return integer[] # (row, col) tuple with the window position
 function vim.api.nvim_win_get_position(window) end
 
 --- Gets the window tabpage
 ---
 --- @param window integer Window handle, or 0 for current window
---- @return integer
+--- @return integer # Tabpage that contains the window
 function vim.api.nvim_win_get_tabpage(window) end
 
 --- Gets a window-scoped (w:) variable
 ---
 --- @param window integer Window handle, or 0 for current window
 --- @param name string Variable name
---- @return any
+--- @return any # Variable value
 function vim.api.nvim_win_get_var(window, name) end
 
 --- Gets the window width
 ---
 --- @param window integer Window handle, or 0 for current window
---- @return integer
+--- @return integer # Width as a count of columns
 function vim.api.nvim_win_get_width(window) end
 
 --- Closes the window and hide the buffer it contains (like `:hide` with a
 --- `window-ID`).
 ---
---- Like `:hide` the buffer becomes hidden unless another window is editing
---- it, or 'bufhidden' is `unload`, `delete` or `wipe` as opposed to `:close`
---- or `nvim_win_close()`, which will close the buffer.
+--- Like `:hide` the buffer becomes hidden unless another window is editing it,
+--- or 'bufhidden' is `unload`, `delete` or `wipe` as opposed to `:close` or
+--- `nvim_win_close()`, which will close the buffer.
 ---
 --- @param window integer Window handle, or 0 for current window
 function vim.api.nvim_win_hide(window) end
@@ -2246,7 +2437,7 @@ function vim.api.nvim_win_hide(window) end
 --- Checks if a window is valid
 ---
 --- @param window integer Window handle, or 0 for current window
---- @return boolean
+--- @return boolean # true if the window is valid, false otherwise
 function vim.api.nvim_win_is_valid(window) end
 
 --- Sets the current buffer in a window, without side effects
@@ -2261,12 +2452,15 @@ function vim.api.nvim_win_set_buf(window, buffer) end
 --- When reconfiguring a window, absent option keys will not be changed.
 --- `row`/`col` and `relative` must be reconfigured together.
 ---
+---
+--- @see vim.api.nvim_open_win
 --- @param window integer Window handle, or 0 for current window
---- @param config vim.api.keyset.win_config Map defining the window configuration, see `nvim_open_win()`
+--- @param config vim.api.keyset.win_config Map defining the window configuration,
+--- see `nvim_open_win()`
 function vim.api.nvim_win_set_config(window, config) end
 
---- Sets the (1,0)-indexed cursor position in the window. `api-indexing` This
---- scrolls the window even if it is not the current one.
+--- Sets the (1,0)-indexed cursor position in the window. `api-indexing`
+--- This scrolls the window even if it is not the current one.
 ---
 --- @param window integer Window handle, or 0 for current window
 --- @param pos integer[] (row, col) tuple representing the new position
@@ -2278,9 +2472,9 @@ function vim.api.nvim_win_set_cursor(window, pos) end
 --- @param height integer Height as a count of rows
 function vim.api.nvim_win_set_height(window, height) end
 
---- Set highlight namespace for a window. This will use highlights defined
---- with `nvim_set_hl()` for this namespace, but fall back to global
---- highlights (ns=0) when missing.
+--- Set highlight namespace for a window. This will use highlights defined with
+--- `nvim_set_hl()` for this namespace, but fall back to global highlights (ns=0) when
+--- missing.
 ---
 --- This takes precedence over the 'winhighlight' option.
 ---
@@ -2308,28 +2502,32 @@ function vim.api.nvim_win_set_var(window, name, value) end
 --- @param width integer Width as a count of columns
 function vim.api.nvim_win_set_width(window, width) end
 
---- Computes the number of screen lines occupied by a range of text in a given
---- window. Works for off-screen text and takes folds into account.
+--- Computes the number of screen lines occupied by a range of text in a given window.
+--- Works for off-screen text and takes folds into account.
 ---
---- Diff filler or virtual lines above a line are counted as a part of that
---- line, unless the line is on "start_row" and "start_vcol" is specified.
+--- Diff filler or virtual lines above a line are counted as a part of that line,
+--- unless the line is on "start_row" and "start_vcol" is specified.
 ---
---- Diff filler or virtual lines below the last buffer line are counted in the
---- result when "end_row" is omitted.
+--- Diff filler or virtual lines below the last buffer line are counted in the result
+--- when "end_row" is omitted.
 ---
 --- Line indexing is similar to `nvim_buf_get_text()`.
 ---
+--- @see `:help virtcol()` for text width.
 --- @param window integer Window handle, or 0 for current window.
 --- @param opts vim.api.keyset.win_text_height Optional parameters:
----             • start_row: Starting line index, 0-based inclusive. When
----               omitted start at the very top.
----             • end_row: Ending line index, 0-based inclusive. When omitted
----               end at the very bottom.
----             • start_vcol: Starting virtual column index on "start_row",
----               0-based inclusive, rounded down to full screen lines. When
----               omitted include the whole line.
----             • end_vcol: Ending virtual column index on "end_row", 0-based
----               exclusive, rounded up to full screen lines. When omitted
----               include the whole line.
---- @return table<string,any>
+--- - start_row: Starting line index, 0-based inclusive.
+---              When omitted start at the very top.
+--- - end_row: Ending line index, 0-based inclusive.
+---            When omitted end at the very bottom.
+--- - start_vcol: Starting virtual column index on "start_row",
+---               0-based inclusive, rounded down to full screen lines.
+---               When omitted include the whole line.
+--- - end_vcol: Ending virtual column index on "end_row",
+---             0-based exclusive, rounded up to full screen lines.
+---             When omitted include the whole line.
+--- @return table<string,any> # Dict containing text height information, with these keys:
+--- - all: The total number of screen lines occupied by the range.
+--- - fill: The number of diff filler or virtual lines among them.
+---
 function vim.api.nvim_win_text_height(window, opts) end
diff --git a/runtime/lua/vim/_meta/api_keysets.lua b/runtime/lua/vim/_meta/api_keysets.lua
index f7cd92a3b2..2fe5c32faf 100644
--- a/runtime/lua/vim/_meta/api_keysets.lua
+++ b/runtime/lua/vim/_meta/api_keysets.lua
@@ -197,6 +197,9 @@ error('Cannot require a meta file')
 --- @field desc? string
 --- @field replace_keycodes? boolean
 
+--- @class vim.api.keyset.ns_opts
+--- @field wins? any[]
+
 --- @class vim.api.keyset.open_term
 --- @field on_input? function
 --- @field force_crlf? boolean
diff --git a/runtime/lua/vim/_meta/api_keysets_extra.lua b/runtime/lua/vim/_meta/api_keysets_extra.lua
index 76b56b04e7..81bce50746 100644
--- a/runtime/lua/vim/_meta/api_keysets_extra.lua
+++ b/runtime/lua/vim/_meta/api_keysets_extra.lua
@@ -23,16 +23,16 @@ error('Cannot require a meta file')
 --- @field conceal? boolean
 --- @field spell? boolean
 --- @field ui_watched? boolean
---- @field url? boolean
+--- @field url? string
 --- @field hl_mode? string
 ---
---- @field virt_text? {[1]: string, [2]: string}[]
+--- @field virt_text? [string, string][]
 --- @field virt_text_hide? boolean
 --- @field virt_text_repeat_linebreak? boolean
 --- @field virt_text_win_col? integer
 --- @field virt_text_pos? string
 ---
---- @field virt_lines? {[1]: string, [2]: string}[][]
+--- @field virt_lines? [string, string][][]
 --- @field virt_lines_above? boolean
 --- @field virt_lines_leftcol? boolean
 ---
@@ -43,11 +43,17 @@ error('Cannot require a meta file')
 --- @field line_hl_group? string
 --- @field cursorline_hl_group? string
 
---- @class vim.api.keyset.get_extmark_item
+--- @class vim.api.keyset.get_extmark_item_by_id
 --- @field [1] integer row
 --- @field [2] integer col
 --- @field [3] vim.api.keyset.extmark_details?
 
+--- @class vim.api.keyset.get_extmark_item
+--- @field [1] integer extmark_id
+--- @field [2] integer row
+--- @field [3] integer col
+--- @field [4] vim.api.keyset.extmark_details?
+
 --- @class vim.api.keyset.get_mark
 --- @field [1] integer row
 --- @field [2] integer col
@@ -96,20 +102,29 @@ error('Cannot require a meta file')
 --- @field strikethrough? true
 --- @field altfont? true
 --- @field nocombine? true
-
---- @class vim.api.keyset.hl_info.cterm : vim.api.keyset.hl_info.base
 --- @field ctermfg? integer
 --- @field ctermbg? integer
+
+--- @class vim.api.keyset.hl_info.cterm : vim.api.keyset.hl_info.base
 --- @field foreground? integer
 --- @field background? integer
 
---- @class vim.api.keyset.hl_info : vim.api.keyset.hl_info.base
+--- @class vim.api.keyset.get_hl_info : vim.api.keyset.hl_info.base
 --- @field fg? integer
 --- @field bg? integer
 --- @field sp? integer
 --- @field default? true
+--- @field blend? integer
+--- @field cterm? vim.api.keyset.hl_info.cterm
+
+--- @class vim.api.keyset.set_hl_info : vim.api.keyset.hl_info.base
+--- @field fg? integer|string
+--- @field bg? integer|string
+--- @field sp? integer|string
+--- @field default? true
 --- @field link? string
 --- @field blend? integer
+--- @field force? true
 --- @field cterm? vim.api.keyset.hl_info.cterm
 
 --- @class vim.api.keyset.get_mode
diff --git a/runtime/lua/vim/_meta/builtin.lua b/runtime/lua/vim/_meta/builtin.lua
index 75737bd040..13bd1c1294 100644
--- a/runtime/lua/vim/_meta/builtin.lua
+++ b/runtime/lua/vim/_meta/builtin.lua
@@ -121,6 +121,7 @@ function vim.stricmp(a, b) end
 --- @param str string
 --- @param index integer
 --- @param use_utf16? boolean
+--- @return integer
 function vim.str_byteindex(str, index, use_utf16) end
 
 --- Gets a list of the starting byte positions of each UTF-8 codepoint in the given string.
@@ -181,8 +182,8 @@ function vim.str_utf_end(str, index) end
 --- that sequence.
 --- @param str string
 --- @param index? integer
---- @return integer UTF-32 index
---- @return integer UTF-16 index
+--- @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
@@ -247,7 +248,7 @@ function vim.schedule(fn) end
 ---     - 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
+--- 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.
 ---
@@ -281,6 +282,8 @@ function vim.wait(time, callback, interval, fast_only) end
 --- end)
 --- ```
 ---
+--- @since 0
+---
 --- @param ns integer
 --- @param options table<string, any>
 --- @param callback fun()
diff --git a/runtime/lua/vim/_meta/builtin_types.lua b/runtime/lua/vim/_meta/builtin_types.lua
index 9f0d2e7038..aca6649957 100644
--- a/runtime/lua/vim/_meta/builtin_types.lua
+++ b/runtime/lua/vim/_meta/builtin_types.lua
@@ -25,7 +25,7 @@
 --- @field variables table<string,any>
 --- @field windows integer[]
 
---- @alias vim.fn.getjumplist.ret {[1]: vim.fn.getjumplist.ret.item[], [2]: integer}
+--- @alias vim.fn.getjumplist.ret [vim.fn.getjumplist.ret.item[], integer]
 
 --- @class vim.fn.getjumplist.ret.item
 --- @field bufnr integer
@@ -34,6 +34,11 @@
 --- @field filename? string
 --- @field lnum integer
 
+--- @class vim.fn.getmarklist.ret.item
+--- @field mark string
+--- @field pos [integer, integer, integer, integer]
+--- @field file string
+
 --- @class vim.fn.getmousepos.ret
 --- @field screenrow integer
 --- @field screencol integer
@@ -135,3 +140,69 @@
 --- @field sid string
 --- @field variables? table<string, any>
 --- @field version 1
+
+--- @class vim.fn.undotree.entry
+---
+--- Undo sequence number.  Same as what appears in
+--- \|:undolist|.
+--- @field seq integer
+---
+--- Timestamp when the change happened.  Use
+--- \|strftime()| to convert to something readable.
+--- @field time integer
+---
+--- Only appears in the item that is the last one
+--- that was added.  This marks the last change
+--- and where further changes will be added.
+--- @field newhead? integer
+---
+--- Only appears in the item that is the last one
+--- that was undone.  This marks the current
+--- position in the undo tree, the block that will
+--- be used by a redo command.  When nothing was
+--- undone after the last change this item will
+--- not appear anywhere.
+--- @field curhead? integer
+---
+--- Only appears on the last block before a file
+--- write.  The number is the write count.  The
+--- first write has number 1, the last one the
+--- "save_last" mentioned above.
+--- @field save integer
+---
+--- Alternate entry.  This is again a List of undo
+--- blocks.  Each item may again have an "alt"
+--- item.
+--- @field alt vim.fn.undotree.entry[]
+
+--- @class vim.fn.undotree.ret
+---
+--- The highest undo sequence number used.
+--- @field seq_last integer
+---
+--- The sequence number of the current position in
+--- the undo tree.  This differs from "seq_last"
+--- when some changes were undone.
+--- @field seq_cur integer
+---
+--- Time last used for |:earlier| and related
+--- commands.  Use |strftime()| to convert to
+--- something readable.
+--- @field time_cur integer
+---
+--- Number of the last file write.  Zero when no
+--- write yet.
+--- @field save_last integer
+---
+--- Number of the current position in the undo
+--- tree.
+--- @field save_cur integer
+---
+--- Non-zero when the last undo block was synced.
+--- This happens when waiting from input from the
+--- user.  See |undo-blocks|.
+--- @field synced integer
+---
+--- A list of dictionaries with information about
+--- undo blocks.
+--- @field entries vim.fn.undotree.entry[]
diff --git a/runtime/lua/vim/_meta/diff.lua b/runtime/lua/vim/_meta/diff.lua
index 617bc87f59..4803ed4775 100644
--- a/runtime/lua/vim/_meta/diff.lua
+++ b/runtime/lua/vim/_meta/diff.lua
@@ -11,19 +11,19 @@
 ---   - `count_a` (`integer`): Hunk size in {a}.
 ---   - `start_b` (`integer`): Start line of hunk in {b}.
 ---   - `count_b` (`integer`): Hunk size in {b}.
---- @field on_hunk fun(start_a: integer, count_a: integer, start_b: integer, count_b: integer): integer
+--- @field on_hunk? fun(start_a: integer, count_a: integer, start_b: integer, count_b: integer): integer?
 ---
 --- Form of the returned diff:
 ---   - `unified`: String in unified format.
 ---   - `indices`: Array of hunk locations.
 --- Note: This option is ignored if `on_hunk` is used.
 --- (default: `'unified'`)
---- @field result_type 'unified'|'indices'
+--- @field result_type? 'unified'|'indices'
 ---
 --- Run linematch on the resulting hunks from xdiff. When integer, only hunks
 --- upto this size in lines are run through linematch.
 --- Requires `result_type = indices`, ignored otherwise.
---- @field linematch boolean|integer
+--- @field linematch? boolean|integer
 ---
 --- Diff algorithm to use. Values:
 ---   - `myers`: the default algorithm
@@ -31,15 +31,15 @@
 ---   - `patience`: patience diff algorithm
 ---   - `histogram`: histogram diff algorithm
 --- (default: `'myers'`)
---- @field algorithm 'myers'|'minimal'|'patience'|'histogram'
---- @field ctxlen integer Context length
---- @field interhunkctxlen integer Inter hunk context length
---- @field ignore_whitespace boolean Ignore whitespace
---- @field ignore_whitespace_change boolean Ignore whitespace change
---- @field ignore_whitespace_change_at_eol boolean Ignore whitespace change at end-of-line.
---- @field ignore_cr_at_eol boolean Ignore carriage return at end-of-line
---- @field ignore_blank_lines boolean Ignore blank lines
---- @field indent_heuristic boolean Use the indent heuristic for the internal diff library.
+--- @field algorithm? 'myers'|'minimal'|'patience'|'histogram'
+--- @field ctxlen? integer Context length
+--- @field interhunkctxlen? integer Inter hunk context length
+--- @field ignore_whitespace? boolean Ignore whitespace
+--- @field ignore_whitespace_change? boolean Ignore whitespace change
+--- @field ignore_whitespace_change_at_eol? boolean Ignore whitespace change at end-of-line.
+--- @field ignore_cr_at_eol? boolean Ignore carriage return at end-of-line
+--- @field ignore_blank_lines? boolean Ignore blank lines
+--- @field indent_heuristic? boolean Use the indent heuristic for the internal diff library.
 
 -- luacheck: no unused args
 
@@ -65,7 +65,7 @@
 ---
 ---@param a string First string to compare
 ---@param b string Second string to compare
----@param opts vim.diff.Opts
+---@param opts? vim.diff.Opts
 ---@return string|integer[][]?
 ---     See {opts.result_type}. `nil` if {opts.on_hunk} is given.
 function vim.diff(a, b, opts) end
diff --git a/runtime/lua/vim/_meta/lpeg.lua b/runtime/lua/vim/_meta/lpeg.lua
index 73b3375c82..d354de95df 100644
--- a/runtime/lua/vim/_meta/lpeg.lua
+++ b/runtime/lua/vim/_meta/lpeg.lua
@@ -2,7 +2,7 @@
 error('Cannot require a meta file')
 
 -- These types were taken from https://github.com/LuaCATS/lpeg
--- (based on revision e6789e28e5b91a4a277a2a03081d708c403a3e34)
+-- (based on revision 33f4ff5343a64cf613a0634d70092fbc2b64291b)
 -- with types being renamed to include the vim namespace and with some descriptions made less verbose.
 
 --- @brief <pre>help
@@ -22,17 +22,18 @@ vim.lpeg = {}
 
 --- @nodoc
 --- @class vim.lpeg.Pattern
+--- @operator len: vim.lpeg.Pattern
 --- @operator unm: vim.lpeg.Pattern
 --- @operator add(vim.lpeg.Pattern): vim.lpeg.Pattern
 --- @operator sub(vim.lpeg.Pattern): vim.lpeg.Pattern
 --- @operator mul(vim.lpeg.Pattern): vim.lpeg.Pattern
 --- @operator mul(vim.lpeg.Capture): vim.lpeg.Pattern
 --- @operator div(string): vim.lpeg.Capture
---- @operator div(number): vim.lpeg.Capture
+--- @operator div(integer): vim.lpeg.Capture
 --- @operator div(table): vim.lpeg.Capture
 --- @operator div(function): vim.lpeg.Capture
---- @operator pow(number): vim.lpeg.Pattern
---- @operator mod(function): nil
+--- @operator pow(integer): vim.lpeg.Pattern
+--- @operator mod(function): vim.lpeg.Capture
 local Pattern = {}
 
 --- @alias vim.lpeg.Capture vim.lpeg.Pattern
@@ -55,11 +56,12 @@ local Pattern = {}
 --- assert(pattern:match('1 hello') == nil)
 --- ```
 ---
---- @param pattern vim.lpeg.Pattern
+--- @param pattern vim.lpeg.Pattern|string|integer|boolean|table|function
 --- @param subject string
 --- @param init? integer
---- @return integer|vim.lpeg.Capture|nil
-function vim.lpeg.match(pattern, subject, init) end
+--- @param ... any
+--- @return any ...
+function vim.lpeg.match(pattern, subject, init, ...) end
 
 --- Matches the given `pattern` against the `subject` string. If the match succeeds, returns the
 --- index in the subject of the first character after the match, or the captured values (if the
@@ -81,8 +83,9 @@ function vim.lpeg.match(pattern, subject, init) end
 ---
 --- @param subject string
 --- @param init? integer
---- @return integer|vim.lpeg.Capture|nil
-function Pattern:match(subject, init) end
+--- @param ... any
+--- @return any ...
+function Pattern:match(subject, init, ...) end
 
 --- Returns the string `"pattern"` if the given value is a pattern, otherwise `nil`.
 ---
@@ -123,7 +126,7 @@ function vim.lpeg.P(value) end
 --- Pattern `patt` must match only strings with some fixed length, and it cannot contain captures.
 --- Like the `and` predicate, this pattern never consumes any input, independently of success or failure.
 ---
---- @param pattern vim.lpeg.Pattern
+--- @param pattern vim.lpeg.Pattern|string|integer|boolean|table
 --- @return vim.lpeg.Pattern
 function vim.lpeg.B(pattern) end
 
@@ -163,7 +166,7 @@ function vim.lpeg.S(string) end
 --- assert(b:match('(') == nil)
 --- ```
 ---
---- @param v string|integer
+--- @param v boolean|string|number|function|table|thread|userdata|lightuserdata 
 --- @return vim.lpeg.Pattern
 function vim.lpeg.V(v) end
 
@@ -227,7 +230,7 @@ function vim.lpeg.locale(tab) end
 --- assert(c == 'c')
 --- ```
 ---
---- @param patt vim.lpeg.Pattern
+--- @param patt vim.lpeg.Pattern|string|integer|boolean|table|function
 --- @return vim.lpeg.Capture
 function vim.lpeg.C(patt) end
 
@@ -258,7 +261,7 @@ function vim.lpeg.Cc(...) end
 --- `func(...func(func(C1, C2), C3)...,Cn)`, that is, it will fold (or accumulate, or reduce) the captures from
 --- `patt` using function `func`. This capture assumes that `patt` should produce at least one capture with at
 --- least one value (of any type), which becomes the initial value of an accumulator. (If you need a specific
---- initial value, you may prefix a constant captureto `patt`.) For each subsequent capture, LPeg calls `func`
+--- initial value, you may prefix a constant capture to `patt`.) For each subsequent capture, LPeg calls `func`
 --- with this accumulator as the first argument and all values produced by the capture as extra arguments;
 --- the first result from this call becomes the new value for the accumulator. The final value of the accumulator
 --- becomes the captured value.
@@ -273,7 +276,7 @@ function vim.lpeg.Cc(...) end
 --- assert(sum:match('10,30,43') == 83)
 --- ```
 ---
---- @param patt vim.lpeg.Pattern
+--- @param patt vim.lpeg.Pattern|string|integer|boolean|table|function
 --- @param func fun(acc, newvalue)
 --- @return vim.lpeg.Capture
 function vim.lpeg.Cf(patt, func) end
@@ -282,7 +285,7 @@ function vim.lpeg.Cf(patt, func) end
 --- The group may be anonymous (if no name is given) or named with the given name (which
 --- can be any non-nil Lua value).
 ---
---- @param patt vim.lpeg.Pattern
+--- @param patt vim.lpeg.Pattern|string|integer|boolean|table|function
 --- @param name? string
 --- @return vim.lpeg.Capture
 function vim.lpeg.Cg(patt, name) end
@@ -320,7 +323,7 @@ function vim.lpeg.Cp() end
 --- assert(gsub('Hello, xxx!', 'xxx', 'World') == 'Hello, World!')
 --- ```
 ---
---- @param patt vim.lpeg.Pattern
+--- @param patt vim.lpeg.Pattern|string|integer|boolean|table|function
 --- @return vim.lpeg.Capture
 function vim.lpeg.Cs(patt) end
 
@@ -329,7 +332,7 @@ function vim.lpeg.Cs(patt) end
 --- Moreover, for each named capture group created by `patt`, the first value of the group is put into
 --- the table with the group name as its key. The captured value is only the table.
 ---
---- @param patt vim.lpeg.Pattern|''
+--- @param patt vim.lpeg.Pattern|string|integer|boolean|table|function
 --- @return vim.lpeg.Capture
 function vim.lpeg.Ct(patt) end
 
@@ -343,7 +346,7 @@ function vim.lpeg.Ct(patt) end
 --- (so, to return true is equivalent to return `i`). If the call returns `false`, `nil`, or no value, the match fails.
 --- Any extra values returned by the function become the values produced by the capture.
 ---
---- @param patt vim.lpeg.Pattern
---- @param fn function
+--- @param patt vim.lpeg.Pattern|string|integer|boolean|table|function
+--- @param fn fun(s: string, i: integer, ...: any): (position: boolean|integer, ...: any)
 --- @return vim.lpeg.Capture
 function vim.lpeg.Cmt(patt, fn) end
diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua
index 428b7c4d4f..ce3ff4f861 100644
--- a/runtime/lua/vim/_meta/options.lua
+++ b/runtime/lua/vim/_meta/options.lua
@@ -544,7 +544,7 @@ vim.wo.bri = vim.wo.breakindent
 --- 		    applying 'breakindent', even if the resulting
 --- 		    text should normally be narrower. This prevents
 --- 		    text indented almost to the right window border
---- 		    occupying lot of vertical space when broken.
+--- 		    occupying lots of vertical space when broken.
 --- 		    (default: 20)
 --- 	shift:{n}   After applying 'breakindent', the wrapped line's
 --- 		    beginning will be shifted by the given number of
@@ -558,9 +558,9 @@ vim.wo.bri = vim.wo.breakindent
 --- 	list:{n}    Adds an additional indent for lines that match a
 --- 		    numbered or bulleted list (using the
 --- 		    'formatlistpat' setting).
---- 	list:-1	    Uses the length of a match with 'formatlistpat'
---- 		    for indentation.
 --- 		    (default: 0)
+--- 	list:-1	    Uses the width of a match with 'formatlistpat' for
+--- 		    indentation.
 --- 	column:{n}  Indent at column {n}. Will overrule the other
 --- 		    sub-options. Note: an additional indent may be
 --- 		    added for the 'showbreak' setting.
@@ -731,11 +731,12 @@ vim.go.cd = vim.go.cdpath
 --- The key used in Command-line Mode to open the command-line window.
 --- Only non-printable keys are allowed.
 --- The key can be specified as a single character, but it is difficult to
---- type.  The preferred way is to use the <> notation.  Examples:
+--- type.  The preferred way is to use `key-notation` (e.g. <Up>, <C-F>) or
+--- a letter preceded with a caret (e.g. `^F` is CTRL-F).  Examples:
 ---
 --- ```vim
---- 	exe "set cedit=\\<C-Y>"
---- 	exe "set cedit=\\<Esc>"
+--- 	set cedit=^Y
+--- 	set cedit=<Esc>
 --- ```
 --- `Nvi` also has this option, but it only uses the first character.
 --- See `cmdwin`.
@@ -785,6 +786,20 @@ vim.bo.channel = vim.o.channel
 --- 	v:fname_in		name of the input file
 --- 	v:fname_out		name of the output file
 --- Note that v:fname_in and v:fname_out will never be the same.
+---
+--- The advantage of using a function call without arguments is that it is
+--- faster, see `expr-option-function`.
+---
+--- If the 'charconvert' expression starts with s: or `<SID>`, then it is
+--- replaced with the script ID (`local-function`). Example:
+---
+--- ```vim
+--- 	set charconvert=s:MyConvert()
+--- 	set charconvert=<SID>SomeConvert()
+--- ```
+--- Otherwise the expression is evaluated in the context of the script
+--- where the option was set, thus script-local items are available.
+---
 --- This option cannot be set from a `modeline` or in the `sandbox`, for
 --- security reasons.
 ---
@@ -899,11 +914,10 @@ vim.go.cb = vim.go.clipboard
 --- used.  The command-line will cover the last line of the screen when
 --- shown.
 ---
---- WARNING: `cmdheight=0` is considered experimental. Expect some
---- unwanted behaviour. Some 'shortmess' flags and similar
---- mechanism might fail to take effect, causing unwanted hit-enter
---- prompts.  Some informative messages, both from Nvim itself and
---- plugins, will not be displayed.
+--- WARNING: `cmdheight=0` is EXPERIMENTAL. Expect some unwanted behaviour.
+--- Some 'shortmess' flags and similar mechanism might fail to take effect,
+--- causing unwanted hit-enter prompts.  Some informative messages, both
+--- from Nvim itself and plugins, will not be displayed.
 ---
 --- @type integer
 vim.o.cmdheight = 1
@@ -974,8 +988,8 @@ vim.bo.comments = vim.o.comments
 vim.bo.com = vim.bo.comments
 
 --- A template for a comment.  The "%s" in the value is replaced with the
---- comment text. For example, C uses "/*%s*/". Used for `commenting` and to
---- add markers for folding, see `fold-marker`.
+--- comment text, and should be padded with a space when possible.
+--- Used for `commenting` and to add markers for folding, see `fold-marker`.
 ---
 --- @type string
 vim.o.commentstring = ""
@@ -1040,6 +1054,19 @@ vim.o.cfu = vim.o.completefunc
 vim.bo.completefunc = vim.o.completefunc
 vim.bo.cfu = vim.bo.completefunc
 
+--- A comma-separated list of `complete-items` that controls the alignment
+--- and display order of items in the popup menu during Insert mode
+--- completion. The supported values are abbr, kind, and menu. These
+--- options allow to customize how the completion items are shown in the
+--- popup menu.  Note: must always contain those three values in any
+--- order.
+---
+--- @type string
+vim.o.completeitemalign = "abbr,kind,menu"
+vim.o.cia = vim.o.completeitemalign
+vim.go.completeitemalign = vim.o.completeitemalign
+vim.go.cia = vim.go.completeitemalign
+
 --- A comma-separated list of options for Insert mode completion
 --- `ins-completion`.  The supported values are:
 ---
@@ -1061,6 +1088,10 @@ vim.bo.cfu = vim.bo.completefunc
 --- 	    completion in the preview window.  Only works in
 --- 	    combination with "menu" or "menuone".
 ---
+---    popup    Show extra information about the currently selected
+--- 	    completion in a popup window.  Only works in combination
+--- 	    with "menu" or "menuone".  Overrides "preview".
+---
 ---    noinsert Do not insert any text for a match until the user selects
 --- 	    a match from the menu. Only works in combination with
 --- 	    "menu" or "menuone". No effect if "longest" is present.
@@ -1069,13 +1100,19 @@ vim.bo.cfu = vim.bo.completefunc
 --- 	    select one from the menu. Only works in combination with
 --- 	    "menu" or "menuone".
 ---
----    popup    Show extra information about the currently selected
---- 	    completion in a popup window.  Only works in combination
---- 	    with "menu" or "menuone".  Overrides "preview".
+---    fuzzy    Enable `fuzzy-matching` for completion candidates. This
+--- 	    allows for more flexible and intuitive matching, where
+--- 	    characters can be skipped and matches can be found even
+--- 	    if the exact sequence is not typed.  Only makes a
+--- 	    difference how completion candidates are reduced from the
+--- 	    list of alternatives, but not how the candidates are
+--- 	    collected (using different completion types).
 ---
 --- @type string
 vim.o.completeopt = "menu,preview"
 vim.o.cot = vim.o.completeopt
+vim.bo.completeopt = vim.o.completeopt
+vim.bo.cot = vim.bo.completeopt
 vim.go.completeopt = vim.o.completeopt
 vim.go.cot = vim.go.completeopt
 
@@ -1805,9 +1842,12 @@ vim.go.ead = vim.go.eadirection
 
 --- When on all Unicode emoji characters are considered to be full width.
 --- This excludes "text emoji" characters, which are normally displayed as
---- single width.  Unfortunately there is no good specification for this
---- and it has been determined on trial-and-error basis.  Use the
---- `setcellwidths()` function to change the behavior.
+--- single width. However, such "text emoji" are treated as full-width
+--- emoji if they are followed by the U+FE0F variant selector.
+---
+--- Unfortunately there is no good specification for this and it has been
+--- determined on trial-and-error basis.  Use the `setcellwidths()`
+--- function to change the behavior.
 ---
 --- @type boolean
 vim.o.emoji = true
@@ -2177,7 +2217,7 @@ vim.go.fic = vim.go.fileignorecase
 --- ```
 --- `FileType` `filetypes`
 --- When a dot appears in the value then this separates two filetype
---- names.  Example: >c
+--- names, it should therefore not be used for a filetype.  Example: >c
 --- 	/* vim: set filetype=c.doxygen : */
 --- ```
 --- This will use the "c" filetype first, then the "doxygen" filetype.
@@ -2185,7 +2225,7 @@ vim.go.fic = vim.go.fileignorecase
 --- one dot may appear.
 --- This option is not copied to another buffer, independent of the 's' or
 --- 'S' flag in 'cpoptions'.
---- Only normal file name characters can be used, `/\*?[|<>` are illegal.
+--- Only alphanumeric characters, '-' and '_' can be used.
 ---
 --- @type string
 vim.o.filetype = ""
@@ -2500,6 +2540,9 @@ vim.wo.fdt = vim.wo.foldtext
 --- This will invoke the mylang#Format() function in the
 --- autoload/mylang.vim file in 'runtimepath'. `autoload`
 ---
+--- The advantage of using a function call without arguments is that it is
+--- faster, see `expr-option-function`.
+---
 --- The expression is also evaluated when 'textwidth' is set and adding
 --- text beyond that limit.  This happens under the same conditions as
 --- when internal formatting is used.  Make sure the cursor is kept in the
@@ -3265,12 +3308,15 @@ vim.go.inc = vim.go.include
 --- the script ID (`local-function`). Example:
 ---
 --- ```vim
---- 	setlocal includeexpr=s:MyIncludeExpr(v:fname)
---- 	setlocal includeexpr=<SID>SomeIncludeExpr(v:fname)
+--- 	setlocal includeexpr=s:MyIncludeExpr()
+--- 	setlocal includeexpr=<SID>SomeIncludeExpr()
 --- ```
 --- Otherwise, the expression is evaluated in the context of the script
 --- where the option was set, thus script-local items are available.
 ---
+--- It is more efficient if the value is just a function call without
+--- arguments, see `expr-option-function`.
+---
 --- The expression will be evaluated in the `sandbox` when set from a
 --- modeline, see `sandbox-option`.
 --- This option cannot be set in a modeline when 'modelineexpr' is off.
@@ -3330,7 +3376,7 @@ vim.go.is = vim.go.incsearch
 --- in Insert mode as specified with the 'indentkeys' option.
 --- When this option is not empty, it overrules the 'cindent' and
 --- 'smartindent' indenting.  When 'lisp' is set, this option is
---- is only used when 'lispoptions' contains "expr:1".
+--- only used when 'lispoptions' contains "expr:1".
 --- The expression is evaluated with `v:lnum` set to the line number for
 --- which the indent is to be computed.  The cursor is also in this line
 --- when the expression is evaluated (but it may be moved around).
@@ -3345,6 +3391,9 @@ vim.go.is = vim.go.incsearch
 --- Otherwise, the expression is evaluated in the context of the script
 --- where the option was set, thus script-local items are available.
 ---
+--- The advantage of using a function call without arguments is that it is
+--- faster, see `expr-option-function`.
+---
 --- The expression must return the number of spaces worth of indent.  It
 --- can return "-1" to keep the current indent (this means 'autoindent' is
 --- used for the indent).
@@ -3541,8 +3590,11 @@ vim.go.js = vim.go.joinspaces
 --- 		|alternate-file` or using `mark-motions` try to
 --- 		restore the `mark-view` in which the action occurred.
 ---
+---   clean         Remove unloaded buffers from the jumplist.
+--- 		EXPERIMENTAL: this flag may change in the future.
+---
 --- @type string
-vim.o.jumpoptions = ""
+vim.o.jumpoptions = "clean"
 vim.o.jop = vim.o.jumpoptions
 vim.go.jumpoptions = vim.o.jumpoptions
 vim.go.jop = vim.go.jumpoptions
@@ -3551,7 +3603,7 @@ vim.go.jop = vim.go.jumpoptions
 --- Setting this option to a valid keymap name has the side effect of
 --- setting 'iminsert' to one, so that the keymap becomes effective.
 --- 'imsearch' is also set to one, unless it was -1
---- Only normal file name characters can be used, `/\*?[|<>` are illegal.
+--- Only alphanumeric characters, '.', '-' and '_' can be used.
 ---
 --- @type string
 vim.o.keymap = ""
@@ -3628,7 +3680,7 @@ vim.go.kp = vim.go.keywordprg
 --- part can be in one of two forms:
 --- 1.  A list of pairs.  Each pair is a "from" character immediately
 ---     followed by the "to" character.  Examples: "aA", "aAbBcC".
---- 2.  A list of "from" characters, a semi-colon and a list of "to"
+--- 2.  A list of "from" characters, a semicolon and a list of "to"
 ---     characters.  Example: "abc;ABC"
 --- Example: "aA,fgh;FGH,cCdDeE"
 --- Special characters need to be preceded with a backslash.  These are
@@ -3720,7 +3772,7 @@ vim.go.ls = vim.go.laststatus
 --- update use `:redraw`.
 --- This may occasionally cause display errors.  It is only meant to be set
 --- temporarily when performing an operation where redrawing may cause
---- flickering or cause a slow down.
+--- flickering or cause a slowdown.
 ---
 --- @type boolean
 vim.o.lazyredraw = false
@@ -3820,6 +3872,9 @@ vim.go.lw = vim.go.lispwords
 --- between tabs and spaces and for trailing blanks. Further changed by
 --- the 'listchars' option.
 ---
+--- When 'listchars' does not contain "tab" field, tabs are shown as "^I"
+--- or "<09>", like how unprintable characters are displayed.
+---
 --- The cursor is displayed at the start of the space a Tab character
 --- occupies, not at the end as usual in Normal mode.  To get this cursor
 --- position while displaying Tabs with spaces, use:
@@ -4533,6 +4588,20 @@ vim.go.mouset = vim.go.mousetime
 --- 	    (without "unsigned" it would become "9-2019").
 --- 	    Using CTRL-X on "0" or CTRL-A on "18446744073709551615"
 --- 	    (2^64 - 1) has no effect, overflow is prevented.
+--- blank	If included, treat numbers as signed or unsigned based on
+--- 	preceding whitespace.  If a number with a leading dash has its
+--- 	dash immediately preceded by a non-whitespace character (i.e.,
+--- 	not a tab or a " "), the negative sign won't be considered as
+--- 	part of the number.  For example:
+--- 	    Using CTRL-A on "14" in "Carbon-14" results in "Carbon-15"
+--- 	    (without "blank" it would become "Carbon-13").
+--- 	    Using CTRL-X on "8" in "Carbon -8" results in "Carbon -9"
+--- 	    (because -8 is preceded by whitespace.  If "unsigned" was
+--- 	    set, it would result in "Carbon -7").
+--- 	If this format is included, overflow is prevented as if
+--- 	"unsigned" were set.  If both this format and "unsigned" are
+--- 	included, "unsigned" will take precedence.
+---
 --- Numbers which simply begin with a digit in the range 1-9 are always
 --- considered decimal.  This also happens for numbers that are not
 --- recognized as octal or hex.
@@ -4757,7 +4826,7 @@ vim.go.pm = vim.go.patchmode
 --- ```
 --- To use an environment variable, you probably need to replace the
 --- separator.  Here is an example to append $INCL, in which directory
---- names are separated with a semi-colon:
+--- names are separated with a semicolon:
 ---
 --- ```vim
 --- 	let &path = &path .. "," .. substitute($INCL, ';', ',', 'g')
@@ -5200,6 +5269,9 @@ vim.wo.scr = vim.wo.scroll
 --- Minimum is 1, maximum is 100000.
 --- Only in `terminal` buffers.
 ---
+--- Note: Lines that are not visible and kept in scrollback are not
+--- reflown when the terminal buffer is resized horizontally.
+---
 --- @type integer
 vim.o.scrollback = -1
 vim.o.scbk = vim.o.scrollback
@@ -5764,7 +5836,7 @@ vim.bo.shiftwidth = vim.o.shiftwidth
 vim.bo.sw = vim.bo.shiftwidth
 
 --- This option helps to avoid all the `hit-enter` prompts caused by file
---- messages, for example  with CTRL-G, and to avoid some other messages.
+--- messages, for example with CTRL-G, and to avoid some other messages.
 --- It is a list of flags:
 ---  flag	meaning when present	~
 ---   l	use "999L, 888B" instead of "999 lines, 888 bytes"	*shm-l*
@@ -5781,8 +5853,8 @@ vim.bo.sw = vim.bo.shiftwidth
 --- 	message;  also for quickfix message (e.g., ":cn")
 ---   s	don't give "search hit BOTTOM, continuing at TOP" or	*shm-s*
 --- 	"search hit TOP, continuing at BOTTOM" messages; when using
---- 	the search count do not show "W" after the count message (see
---- 	S below)
+--- 	the search count do not show "W" before the count message
+--- 	(see `shm-S` below)
 ---   t	truncate file message at the start if it is too long	*shm-t*
 --- 	to fit on the command-line, "<" will appear in the left most
 --- 	column; ignored in Ex mode
@@ -5804,7 +5876,11 @@ vim.bo.sw = vim.bo.shiftwidth
 --- 	`:silent` was used for the command; note that this also
 --- 	affects messages from 'autoread' reloading
 ---   S	do not show search count message when searching, e.g.	*shm-S*
---- 	"[1/5]"
+--- 	"[1/5]". When the "S" flag is not present (e.g. search count
+--- 	is shown), the "search hit BOTTOM, continuing at TOP" and
+--- 	"search hit TOP, continuing at BOTTOM" messages are only
+--- 	indicated by a "W" (Mnemonic: Wrapped) letter before the
+--- 	search count statistics.
 ---
 --- This gives you the opportunity to avoid that a change between buffers
 --- requires you to hit <Enter>, but still gives as useful a message as
@@ -6249,7 +6325,7 @@ vim.bo.spo = vim.bo.spelloptions
 --- 		minus two.
 ---
 --- timeout:{millisec}   Limit the time searching for suggestions to
---- 		{millisec} milli seconds.  Applies to the following
+--- 		{millisec} milliseconds.  Applies to the following
 --- 		methods.  When omitted the limit is 5000. When
 --- 		negative there is no limit.
 ---
@@ -6269,9 +6345,11 @@ vim.bo.spo = vim.bo.spelloptions
 --- 		The file is used for all languages.
 ---
 --- expr:{expr}	Evaluate expression {expr}.  Use a function to avoid
---- 		trouble with spaces.  `v:val` holds the badly spelled
---- 		word.  The expression must evaluate to a List of
---- 		Lists, each with a suggestion and a score.
+--- 		trouble with spaces.  Best is to call a function
+--- 		without arguments, see `expr-option-function|.
+--- 		|v:val` holds the badly spelled word.  The expression
+--- 		must evaluate to a List of Lists, each with a
+--- 		suggestion and a score.
 --- 		Example:
 --- 			[['the', 33], ['that', 44]] ~
 --- 		Set 'verbose' and use `z=` to see the scores that the
@@ -6338,7 +6416,8 @@ vim.go.spr = vim.go.splitright
 --- non-blank of the line.  When off the cursor is kept in the same column
 --- (if possible).  This applies to the commands:
 --- - CTRL-D, CTRL-U, CTRL-B, CTRL-F, "G", "H", "M", "L", "gg"
---- - "d", "<<" and ">>" with a linewise operator
+--- - "d", "<<", "==" and ">>" with a linewise operator
+---   (`operator-resulting-pos`)
 --- - "%" with a count
 --- - buffer changing commands (CTRL-^, :bnext, :bNext, etc.)
 --- - Ex commands that only have a line number, e.g., ":25" or ":+".
@@ -6351,7 +6430,6 @@ vim.o.sol = vim.o.startofline
 vim.go.startofline = vim.o.startofline
 vim.go.sol = vim.go.startofline
 
---- EXPERIMENTAL
 --- When non-empty, this option determines the content of the area to the
 --- side of a window, normally containing the fold, sign and number columns.
 --- The format of this option is like that of 'statusline'.
@@ -6359,8 +6437,7 @@ vim.go.sol = vim.go.startofline
 --- Some of the items from the 'statusline' format are different for
 --- 'statuscolumn':
 ---
---- %l	line number of currently drawn line
---- %r	relative line number of currently drawn line
+--- %l	line number column for currently drawn line
 --- %s	sign column for currently drawn line
 --- %C	fold column for currently drawn line
 ---
@@ -6389,11 +6466,8 @@ vim.go.sol = vim.go.startofline
 --- Examples:
 ---
 --- ```vim
---- 	" Relative number with bar separator and click handlers:
---- 	set statuscolumn=%@SignCb@%s%=%T%@NumCb@%r│%T
----
---- 	" Right aligned relative cursor line number:
---- 	let &stc='%=%{v:relnum?v:relnum:v:lnum} '
+--- 	" Line number with bar separator and click handlers:
+--- 	set statuscolumn=%@SignCb@%s%=%T%@NumCb@%l│%T
 ---
 --- 	" Line numbers in hexadecimal for non wrapped part of lines:
 --- 	let &stc='%=%{v:virtnum>0?"":printf("%x",v:lnum)} '
@@ -6799,7 +6873,7 @@ vim.bo.smc = vim.bo.synmaxcol
 --- Syntax autocommand event is triggered with the value as argument.
 --- This option is not copied to another buffer, independent of the 's' or
 --- 'S' flag in 'cpoptions'.
---- Only normal file name characters can be used, `/\*?[|<>` are illegal.
+--- Only alphanumeric characters, '.', '-' and '_' can be used.
 ---
 --- @type string
 vim.o.syntax = ""
@@ -6807,6 +6881,22 @@ vim.o.syn = vim.o.syntax
 vim.bo.syntax = vim.o.syntax
 vim.bo.syn = vim.bo.syntax
 
+--- This option controls the behavior when closing tab pages (e.g., using
+--- `:tabclose`).  When empty Vim goes to the next (right) tab page.
+---
+--- Possible values (comma-separated list):
+---    left		If included, go to the previous tab page instead of
+--- 		the next one.
+---    uselast	If included, go to the previously used tab page if
+--- 		possible.  This option takes precedence over the
+--- 		others.
+---
+--- @type string
+vim.o.tabclose = ""
+vim.o.tcl = vim.o.tabclose
+vim.go.tabclose = vim.o.tabclose
+vim.go.tcl = vim.go.tabclose
+
 --- When non-empty, this option determines the content of the tab pages
 --- line at the top of the Vim window.  When empty Vim will use a default
 --- tab pages line.  See `setting-tabline` for more info.
@@ -7178,7 +7268,7 @@ vim.go.tm = vim.go.timeoutlen
 
 --- When on, the title of the window will be set to the value of
 --- 'titlestring' (if it is not empty), or to:
---- 	filename [+=-] (path) - NVIM
+--- 	filename [+=-] (path) - Nvim
 --- Where:
 --- 	filename	the name of the file being edited
 --- 	-		indicates the file cannot be modified, 'ma' off
@@ -7186,7 +7276,7 @@ vim.go.tm = vim.go.timeoutlen
 --- 	=		indicates the file is read-only
 --- 	=+		indicates the file is read-only and modified
 --- 	(path)		is the path of the file being edited
---- 	- NVIM		the server name `v:servername` or "NVIM"
+--- 	- Nvim		the server name `v:servername` or "Nvim"
 ---
 --- @type boolean
 vim.o.title = false
@@ -7607,9 +7697,14 @@ vim.go.ww = vim.go.whichwrap
 --- Some keys will not work, such as CTRL-C, <CR> and Enter.
 --- <Esc> can be used, but hitting it twice in a row will still exit
 --- command-line as a failsafe measure.
---- Although 'wc' is a number option, you can set it to a special key:
+--- Although 'wc' is a number option, it can be specified as a number, a
+--- single character, a `key-notation` (e.g. <Up>, <C-F>) or a letter
+--- preceded with a caret (e.g. `^F` is CTRL-F):
 ---
 --- ```vim
+--- 	:set wc=27
+--- 	:set wc=X
+--- 	:set wc=^I
 --- 	set wc=<Tab>
 --- ```
 ---
diff --git a/runtime/lua/vim/_meta/regex.lua b/runtime/lua/vim/_meta/regex.lua
index 595ad96319..9c9cd7d29b 100644
--- a/runtime/lua/vim/_meta/regex.lua
+++ b/runtime/lua/vim/_meta/regex.lua
@@ -5,9 +5,9 @@
 --- @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|.
+--- Parses the Vim regex `re` and returns 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
@@ -16,20 +16,22 @@ function vim.regex(re) end
 --- @class vim.regex
 local regex = {} -- luacheck: no unused
 
---- Match the string against the regex. If the string should match the regex
---- precisely, surround the regex with `^` and `$`. If there was a match, the
---- byte indices for the beginning and end of the match are returned. When
---- there is no match, `nil` is returned. Because any integer is "truthy",
---- `regex:match_str()` can be directly used as a condition in an if-statement.
+--- Matches string `str` against this regex. To match the string precisely, surround the regex with
+--- "^" and "$". Returns the byte indices for the start and end of the match, or `nil` if there is
+--- no match. Because any integer is "truthy", `regex:match_str()` can be directly used as
+--- a condition in an if-statement.
 --- @param str string
+--- @return integer? # match start (byte index), or `nil` if no match
+--- @return integer? # match end (byte index), or `nil` if no match
 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}.
+--- Matches line at `line_idx` (zero-based) in buffer `bufnr`. Match is restricted to byte index
+--- range `start` and `end_` if given, otherwise see |regex:match_str()|. Returned byte indices are
+--- relative to `start` if given.
 --- @param bufnr integer
 --- @param line_idx integer
 --- @param start? integer
 --- @param end_? integer
+--- @return integer? # match start (byte index) relative to `start`, or `nil` if no match
+--- @return integer? # match end (byte index) relative to `start`, or `nil` if no match
 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
index c636db3b53..b4e3bf6ca4 100644
--- a/runtime/lua/vim/_meta/spell.lua
+++ b/runtime/lua/vim/_meta/spell.lua
@@ -20,7 +20,7 @@
 --- ```
 ---
 --- @param str string
---- @return {[1]: string, [2]: 'bad'|'rare'|'local'|'caps', [3]: integer}[]
+--- @return [string, 'bad'|'rare'|'local'|'caps', integer][]
 ---   List of tuples with three items:
 ---     - The badly spelled word.
 ---     - The type of the spelling error:
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index f4daacfb7d..3f6deba092 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -15,7 +15,7 @@ error('Cannot require a meta file')
 ---   echo abs(-4)
 --- <  4
 ---
---- @param expr any
+--- @param expr number
 --- @return number
 function vim.fn.abs(expr) end
 
@@ -31,7 +31,7 @@ function vim.fn.abs(expr) end
 ---   echo acos(-0.5)
 --- <  2.094395
 ---
---- @param expr any
+--- @param expr number
 --- @return number
 function vim.fn.acos(expr) end
 
@@ -47,7 +47,7 @@ function vim.fn.acos(expr) end
 ---
 --- @param object any
 --- @param expr any
---- @return any
+--- @return any # Resulting |List| or |Blob|, or 1 if {object} is not a |List| or a |Blob|.
 function vim.fn.add(object, expr) end
 
 --- Bitwise AND on the two arguments.  The arguments are converted
@@ -57,8 +57,8 @@ function vim.fn.add(object, expr) end
 ---   let flag = and(bits, 0x80)
 --- <
 ---
---- @param expr any
---- @param expr1 any
+--- @param expr number
+--- @param expr1 number
 --- @return integer
 vim.fn['and'] = function(expr, expr1) end
 
@@ -86,7 +86,7 @@ function vim.fn.api_info() end
 --- <
 ---
 --- @param lnum integer
---- @param text any
+--- @param text string|string[]
 --- @return 0|1
 function vim.fn.append(lnum, text) end
 
@@ -110,7 +110,7 @@ function vim.fn.append(lnum, text) end
 --- <However, when {text} is an empty list then no error is given
 --- for an invalid {lnum}, since {lnum} isn't actually used.
 ---
---- @param buf any
+--- @param buf integer|string
 --- @param lnum integer
 --- @param text string
 --- @return 0|1
@@ -195,7 +195,7 @@ function vim.fn.asin(expr) end
 --- Also see |assert_fails()|, |assert_nobeep()| and
 --- |assert-return|.
 ---
---- @param cmd any
+--- @param cmd string
 --- @return 0|1
 function vim.fn.assert_beeps(cmd) end
 
@@ -203,16 +203,17 @@ function vim.fn.assert_beeps(cmd) end
 --- added to |v:errors| and 1 is returned.  Otherwise zero is
 --- returned. |assert-return|
 --- The error is in the form "Expected {expected} but got
---- {actual}".  When {msg} is present it is prefixed to that.
+--- {actual}".  When {msg} is present it is prefixed to that,
+--- along with the location of the assert when run from a script.
 ---
 --- There is no automatic conversion, the String "4" is different
 --- from the Number 4.  And the number 4 is different from the
 --- Float 4.0.  The value of 'ignorecase' is not used here, case
 --- always matters.
 --- Example: >vim
----   assert_equal('foo', 'bar')
---- <Will result in a string to be added to |v:errors|:
----   test.vim line 12: Expected 'foo' but got 'bar' ~
+---   call assert_equal('foo', 'bar', 'baz')
+--- <Will add the following to |v:errors|:
+---   test.vim line 12: baz: Expected 'foo' but got 'bar' ~
 ---
 --- @param expected any
 --- @param actual any
@@ -226,8 +227,10 @@ function vim.fn.assert_equal(expected, actual, msg) end
 --- When {fname-one} or {fname-two} does not exist the error will
 --- mention that.
 ---
+--- @param fname-one string
+--- @param fname-two string
 --- @return 0|1
-function vim.fn.assert_equalfile() end
+function vim.fn.assert_equalfile(fname-one, fname-two) end
 
 --- When v:exception does not contain the string {error} an error
 --- message is added to |v:errors|.  Also see |assert-return|.
@@ -254,25 +257,25 @@ function vim.fn.assert_exception(error, msg) end
 --- When {error} is a string it must be found literally in the
 --- first reported error. Most often this will be the error code,
 --- including the colon, e.g. "E123:". >vim
----   assert_fails('bad cmd', 'E987:')
+---   call assert_fails('bad cmd', 'E987:')
 --- <
 --- When {error} is a |List| with one or two strings, these are
 --- used as patterns.  The first pattern is matched against the
 --- first reported error: >vim
----   assert_fails('cmd', ['E987:.*expected bool'])
+---   call assert_fails('cmd', ['E987:.*expected bool'])
 --- <The second pattern, if present, is matched against the last
 --- reported error.  To only match the last error use an empty
 --- string for the first error: >vim
----   assert_fails('cmd', ['', 'E987:'])
+---   call assert_fails('cmd', ['', 'E987:'])
 --- <
 --- If {msg} is empty then it is not used.  Do this to get the
 --- default message when passing the {lnum} argument.
----
+---           *E1115*
 --- When {lnum} is present and not negative, and the {error}
 --- argument is present and matches, then this is compared with
 --- the line number at which the error was reported. That can be
 --- the line number in a function or in a script.
----
+---           *E1116*
 --- When {context} is present it is used as a pattern and matched
 --- against the context (script name or function name) where
 --- {lnum} is located in.
@@ -280,7 +283,7 @@ function vim.fn.assert_exception(error, msg) end
 --- Note that beeping is not considered an error, and some failing
 --- commands only beep.  Use |assert_beeps()| for those.
 ---
---- @param cmd any
+--- @param cmd string
 --- @param error? any
 --- @param msg? any
 --- @param lnum? integer
@@ -291,7 +294,8 @@ function vim.fn.assert_fails(cmd, error, msg, lnum, context) end
 --- When {actual} is not false an error message is added to
 --- |v:errors|, like with |assert_equal()|.
 --- The error is in the form "Expected False but got {actual}".
---- When {msg} is present it is prepended to that.
+--- When {msg} is present it is prefixed to that, along with the
+--- location of the assert when run from a script.
 --- Also see |assert-return|.
 ---
 --- A value is false when it is zero. When {actual} is not a
@@ -309,17 +313,18 @@ function vim.fn.assert_false(actual, msg) end
 --- but got {actual}".  When {msg} is present it is prefixed to
 --- that.
 ---
---- @param lower any
---- @param upper any
---- @param actual any
---- @param msg? any
+--- @param lower number
+--- @param upper number
+--- @param actual number
+--- @param msg? string
 --- @return 0|1
 function vim.fn.assert_inrange(lower, upper, actual, msg) end
 
 --- When {pattern} does not match {actual} an error message is
 --- added to |v:errors|.  Also see |assert-return|.
 --- The error is in the form "Pattern {pattern} does not match
---- {actual}".  When {msg} is present it is prefixed to that.
+--- {actual}".  When {msg} is present it is prefixed to that,
+--- along with the location of the assert when run from a script.
 ---
 --- {pattern} is used as with |expr-=~|: The matching is always done
 --- like 'magic' was set and 'cpoptions' is empty, no matter what
@@ -330,13 +335,13 @@ function vim.fn.assert_inrange(lower, upper, actual, msg) end
 --- Use both to match the whole text.
 ---
 --- Example: >vim
----   assert_match('^f.*o$', 'foobar')
+---   call assert_match('^f.*o$', 'foobar')
 --- <Will result in a string to be added to |v:errors|:
 ---   test.vim line 12: Pattern '^f.*o$' does not match 'foobar' ~
 ---
---- @param pattern any
---- @param actual any
---- @param msg? any
+--- @param pattern string
+--- @param actual string
+--- @param msg? string
 --- @return 0|1
 function vim.fn.assert_match(pattern, actual, msg) end
 
@@ -344,7 +349,7 @@ function vim.fn.assert_match(pattern, actual, msg) end
 --- produces a beep or visual bell.
 --- Also see |assert_beeps()|.
 ---
---- @param cmd any
+--- @param cmd string
 --- @return 0|1
 function vim.fn.assert_nobeep(cmd) end
 
@@ -362,16 +367,16 @@ function vim.fn.assert_notequal(expected, actual, msg) end
 --- |v:errors| when {pattern} matches {actual}.
 --- Also see |assert-return|.
 ---
---- @param pattern any
---- @param actual any
---- @param msg? any
+--- @param pattern string
+--- @param actual string
+--- @param msg? string
 --- @return 0|1
 function vim.fn.assert_notmatch(pattern, actual, msg) end
 
 --- Report a test failure directly, using String {msg}.
 --- Always returns one.
 ---
---- @param msg any
+--- @param msg string
 --- @return 0|1
 function vim.fn.assert_report(msg) end
 
@@ -380,10 +385,11 @@ function vim.fn.assert_report(msg) end
 --- Also see |assert-return|.
 --- A value is |TRUE| when it is a non-zero number or |v:true|.
 --- When {actual} is not a number or |v:true| the assert fails.
---- When {msg} is given it precedes the default message.
+--- When {msg} is given it is prefixed to the default message,
+--- along with the location of the assert when run from a script.
 ---
 --- @param actual any
---- @param msg? any
+--- @param msg? string
 --- @return 0|1
 function vim.fn.assert_true(actual, msg) end
 
@@ -397,7 +403,7 @@ function vim.fn.assert_true(actual, msg) end
 ---   echo atan(-4.01)
 --- <  -1.326405
 ---
---- @param expr any
+--- @param expr number
 --- @return number
 function vim.fn.atan(expr) end
 
@@ -412,8 +418,8 @@ function vim.fn.atan(expr) end
 ---   echo atan2(1, -1)
 --- <  2.356194
 ---
---- @param expr1 any
---- @param expr2 any
+--- @param expr1 number
+--- @param expr2 number
 --- @return number
 function vim.fn.atan2(expr1, expr2) end
 
@@ -439,9 +445,9 @@ function vim.fn.blob2list(blob) end
 --- something went wrong, or browsing is not possible.
 ---
 --- @param save any
---- @param title any
---- @param initdir any
---- @param default any
+--- @param title string
+--- @param initdir string
+--- @param default string
 --- @return 0|1
 function vim.fn.browse(save, title, initdir, default) end
 
@@ -456,8 +462,8 @@ function vim.fn.browse(save, title, initdir, default) end
 --- When the "Cancel" button is hit, something went wrong, or
 --- browsing is not possible, an empty string is returned.
 ---
---- @param title any
---- @param initdir any
+--- @param title string
+--- @param initdir string
 --- @return 0|1
 function vim.fn.browsedir(title, initdir) end
 
@@ -729,7 +735,7 @@ function vim.fn.call(func, arglist, dict) end
 ---
 --- Returns 0.0 if {expr} is not a |Float| or a |Number|.
 ---
---- @param expr any
+--- @param expr number
 --- @return number
 function vim.fn.ceil(expr) end
 
@@ -742,8 +748,8 @@ function vim.fn.ceil(expr) end
 --- For a socket, there is only one stream, and {stream} should be
 --- omitted.
 ---
---- @param id any
---- @param stream? any
+--- @param id integer
+--- @param stream? string
 --- @return 0|1
 function vim.fn.chanclose(id, stream) end
 
@@ -775,8 +781,8 @@ function vim.fn.changenr() end
 --- was created with `"rpc":v:true` then the channel expects RPC
 --- messages, use |rpcnotify()| and |rpcrequest()| instead.
 ---
---- @param id any
---- @param data any
+--- @param id number
+--- @param data string|string[]
 --- @return 0|1
 function vim.fn.chansend(id, data) end
 
@@ -820,8 +826,9 @@ function vim.fn.charclass(string) end
 --- With the cursor on '세' in line 5 with text "여보세요": >vim
 ---   echo charcol('.')  " returns 3
 ---   echo col('.')    " returns 7
+--- <
 ---
---- @param expr any
+--- @param expr string|integer[]
 --- @param winid? integer
 --- @return integer
 function vim.fn.charcol(expr, winid) end
@@ -861,8 +868,8 @@ function vim.fn.charcol(expr, winid) end
 ---
 --- @param string string
 --- @param idx integer
---- @param countcc? any
---- @param utf16? any
+--- @param countcc? boolean
+--- @param utf16? boolean
 --- @return integer
 function vim.fn.charidx(string, idx, countcc, utf16) end
 
@@ -886,6 +893,7 @@ function vim.fn.charidx(string, idx, countcc, utf16) end
 ---      " ... do some work
 ---      call chdir(save_dir)
 ---   endif
+--- <
 ---
 --- @param dir string
 --- @return string
@@ -907,37 +915,37 @@ function vim.fn.cindent(lnum) end
 --- If {win} is specified, use the window with this number or
 --- window ID instead of the current window.
 ---
---- @param win? any
+--- @param win? integer
 function vim.fn.clearmatches(win) end
 
 --- The result is a Number, which is the byte index of the column
---- position given with {expr}.  The accepted positions are:
----     .      the cursor position
----     $      the end of the cursor line (the result is the
----       number of bytes in the cursor line plus one)
----     'x      position of mark x (if the mark is not set, 0 is
----       returned)
----     v       In Visual mode: the start of the Visual area (the
----       cursor is the end).  When not in Visual mode
----       returns the cursor position.  Differs from |'<| in
----       that it's updated right away.
+--- position given with {expr}.
+--- For accepted positions see |getpos()|.
+--- When {expr} is "$", it means the end of the cursor line, so
+--- the result is the number of bytes in the cursor line plus one.
 --- Additionally {expr} can be [lnum, col]: a |List| with the line
 --- and column number. Most useful when the column is "$", to get
 --- the last column of a specific line.  When "lnum" or "col" is
 --- out of range then col() returns zero.
+---
 --- With the optional {winid} argument the values are obtained for
 --- that window instead of the current window.
+---
 --- To get the line number use |line()|.  To get both use
 --- |getpos()|.
+---
 --- For the screen column position use |virtcol()|.  For the
 --- character position use |charcol()|.
+---
 --- Note that only marks in the current file can be used.
+---
 --- Examples: >vim
 ---   echo col(".")      " column of cursor
 ---   echo col("$")      " length of cursor line plus one
 ---   echo col("'t")      " column of mark t
 ---   echo col("'" .. markname)  " column of mark markname
---- <The first column is 1.  Returns 0 if {expr} is invalid or when
+--- <
+--- The first column is 1.  Returns 0 if {expr} is invalid or when
 --- the window with ID {winid} is not found.
 --- For an uppercase mark the column may actually be in another
 --- buffer.
@@ -946,8 +954,9 @@ function vim.fn.clearmatches(win) end
 --- line.  Also, when using a <Cmd> mapping the cursor isn't
 --- moved, this can be used to obtain the column in Insert mode: >vim
 ---   imap <F2> <Cmd>echo col(".").."\n"<CR>
+--- <
 ---
---- @param expr any
+--- @param expr string|integer[]
 --- @param winid? integer
 --- @return integer
 function vim.fn.col(expr, winid) end
@@ -981,8 +990,8 @@ function vim.fn.col(expr, winid) end
 --- <This isn't very useful, but it shows how it works.  Note that
 --- an empty string is returned to avoid a zero being inserted.
 ---
---- @param startcol any
---- @param matches any
+--- @param startcol integer
+--- @param matches any[]
 function vim.fn.complete(startcol, matches) end
 
 --- Add {expr} to the list of matches.  Only to be used by the
@@ -1065,8 +1074,9 @@ function vim.fn.complete_check() end
 ---   call complete_info(['mode'])
 ---   " Get only 'mode' and 'pum_visible'
 ---   call complete_info(['mode', 'pum_visible'])
+--- <
 ---
---- @param what? any
+--- @param what? any[]
 --- @return table
 function vim.fn.complete_info(what) end
 
@@ -1121,10 +1131,10 @@ function vim.fn.complete_info(what) end
 --- don't fit, a vertical layout is used anyway.  For some systems
 --- the horizontal layout is always used.
 ---
---- @param msg any
---- @param choices? any
---- @param default? any
---- @param type? any
+--- @param msg string
+--- @param choices? string
+--- @param default? integer
+--- @param type? string
 --- @return integer
 function vim.fn.confirm(msg, choices, default, type) end
 
@@ -1150,7 +1160,7 @@ function vim.fn.copy(expr) end
 ---   echo cos(-4.01)
 --- <  -0.646043
 ---
---- @param expr any
+--- @param expr number
 --- @return number
 function vim.fn.cos(expr) end
 
@@ -1164,7 +1174,7 @@ function vim.fn.cos(expr) end
 ---   echo cosh(-0.5)
 --- <  -1.127626
 ---
---- @param expr any
+--- @param expr number
 --- @return number
 function vim.fn.cosh(expr) end
 
@@ -1180,10 +1190,10 @@ function vim.fn.cosh(expr) end
 --- occurrences of {expr} is returned. Zero is returned when
 --- {expr} is an empty string.
 ---
---- @param comp any
+--- @param comp string|table|any[]
 --- @param expr any
---- @param ic? any
---- @param start? any
+--- @param ic? boolean
+--- @param start? integer
 --- @return integer
 function vim.fn.count(comp, expr, ic, start) end
 
@@ -1191,7 +1201,7 @@ function vim.fn.count(comp, expr, ic, start) end
 --- from the top of the |context-stack| (see |context-dict|).
 --- If {index} is not given, it is assumed to be 0 (i.e.: top).
 ---
---- @param index? any
+--- @param index? integer
 --- @return table
 function vim.fn.ctxget(index) end
 
@@ -1207,7 +1217,7 @@ function vim.fn.ctxpop() end
 --- which |context-types| to include in the pushed context.
 --- Otherwise, all context types are included.
 ---
---- @param types? any
+--- @param types? string[]
 --- @return any
 function vim.fn.ctxpush(types) end
 
@@ -1216,8 +1226,8 @@ function vim.fn.ctxpush(types) end
 --- {context} is a Dictionary with context data (|context-dict|).
 --- If {index} is not given, it is assumed to be 0 (i.e.: top).
 ---
---- @param context any
---- @param index? any
+--- @param context table
+--- @param index? integer
 --- @return any
 function vim.fn.ctxset(context, index) end
 
@@ -1228,7 +1238,7 @@ function vim.fn.ctxsize() end
 
 --- @param lnum integer
 --- @param col? integer
---- @param off? any
+--- @param off? integer
 --- @return any
 function vim.fn.cursor(lnum, col, off) end
 
@@ -1263,7 +1273,7 @@ function vim.fn.cursor(lnum, col, off) end
 --- position within a <Tab> or after the last character.
 --- Returns 0 when the position could be set, -1 otherwise.
 ---
---- @param list any
+--- @param list integer[]
 --- @return any
 function vim.fn.cursor(list) end
 
@@ -1275,7 +1285,7 @@ function vim.fn.cursor(list) end
 --- Returns |TRUE| if successfully interrupted the program.
 --- Otherwise returns |FALSE|.
 ---
---- @param pid any
+--- @param pid integer
 --- @return any
 function vim.fn.debugbreak(pid) end
 
@@ -1299,7 +1309,7 @@ function vim.fn.debugbreak(pid) end
 --- Also see |copy()|.
 ---
 --- @param expr any
---- @param noref? any
+--- @param noref? boolean
 --- @return any
 function vim.fn.deepcopy(expr, noref) end
 
@@ -1339,9 +1349,9 @@ function vim.fn.delete(fname, flags) end
 --- when using |line()| this refers to the current buffer. Use "$"
 --- to refer to the last line in buffer {buf}.
 ---
---- @param buf any
---- @param first any
---- @param last? any
+--- @param buf integer|string
+--- @param first integer|string
+--- @param last? integer|string
 --- @return any
 function vim.fn.deletebufline(buf, first, last) end
 
@@ -1384,9 +1394,9 @@ function vim.fn.deletebufline(buf, first, last) end
 --- This function can be used by plugins to implement options with
 --- validation and parsing logic.
 ---
---- @param dict any
---- @param pattern any
---- @param callback any
+--- @param dict table
+--- @param pattern string
+--- @param callback function
 --- @return any
 function vim.fn.dictwatcheradd(dict, pattern, callback) end
 
@@ -1395,8 +1405,8 @@ function vim.fn.dictwatcheradd(dict, pattern, callback) end
 --- order for the watcher to be successfully deleted.
 ---
 --- @param dict any
---- @param pattern any
---- @param callback any
+--- @param pattern string
+--- @param callback function
 --- @return any
 function vim.fn.dictwatcherdel(dict, pattern, callback) end
 
@@ -1457,7 +1467,7 @@ function vim.fn.diff_hlID(lnum, col) end
 --- echo digraph_get('aa')    " Returns 'あ'
 --- <
 ---
---- @param chars any
+--- @param chars string
 --- @return any
 function vim.fn.digraph_get(chars) end
 
@@ -1475,7 +1485,7 @@ function vim.fn.digraph_get(chars) end
 --- echo digraph_getlist(1)
 --- <
 ---
---- @param listall? any
+--- @param listall? boolean
 --- @return any
 function vim.fn.digraph_getlist(listall) end
 
@@ -1495,12 +1505,9 @@ function vim.fn.digraph_getlist(listall) end
 --- Example: >vim
 ---   call digraph_set('  ', 'あ')
 --- <
---- Can be used as a |method|: >vim
----   GetString()->digraph_set('あ')
---- <
 ---
---- @param chars any
---- @param digraph any
+--- @param chars string
+--- @param digraph string
 --- @return any
 function vim.fn.digraph_set(chars, digraph) end
 
@@ -1518,11 +1525,7 @@ function vim.fn.digraph_set(chars, digraph) end
 --- <Except that the function returns after the first error,
 --- following digraphs will not be added.
 ---
---- Can be used as a |method|: >vim
----     GetList()->digraph_setlist()
---- <
----
---- @param digraphlist any
+--- @param digraphlist table<integer,string[]>
 --- @return any
 function vim.fn.digraph_setlist(digraphlist) end
 
@@ -1557,7 +1560,7 @@ function vim.fn.environ() end
 --- <Also see |shellescape()| and |fnameescape()|.
 ---
 --- @param string string
---- @param chars any
+--- @param chars string
 --- @return any
 function vim.fn.escape(string, chars) end
 
@@ -1582,25 +1585,32 @@ function vim.fn.eventhandler() end
 --- This function checks if an executable with the name {expr}
 --- exists.  {expr} must be the name of the program without any
 --- arguments.
+---
 --- executable() uses the value of $PATH and/or the normal
---- searchpath for programs.    *PATHEXT*
+--- searchpath for programs.
+---           *PATHEXT*
 --- On MS-Windows the ".exe", ".bat", etc. can optionally be
 --- included.  Then the extensions in $PATHEXT are tried.  Thus if
 --- "foo.exe" does not exist, "foo.exe.bat" can be found.  If
---- $PATHEXT is not set then ".exe;.com;.bat;.cmd" is used.  A dot
+--- $PATHEXT is not set then ".com;.exe;.bat;.cmd" is used.  A dot
 --- by itself can be used in $PATHEXT to try using the name
 --- without an extension.  When 'shell' looks like a Unix shell,
 --- then the name is also tried without adding an extension.
 --- On MS-Windows it only checks if the file exists and is not a
 --- directory, not if it's really executable.
---- On Windows an executable in the same directory as Vim is
---- always found (it is added to $PATH at |startup|).
+--- On MS-Windows an executable in the same directory as the Vim
+--- executable is always found (it's added to $PATH at |startup|).
+---       *NoDefaultCurrentDirectoryInExePath*
+--- On MS-Windows an executable in Vim's current working directory
+--- is also normally found, but this can be disabled by setting
+--- the $NoDefaultCurrentDirectoryInExePath environment variable.
+---
 --- The result is a Number:
 ---   1  exists
 ---   0  does not exist
 --- |exepath()| can be used to get the full path of an executable.
 ---
---- @param expr any
+--- @param expr string
 --- @return 0|1
 function vim.fn.executable(expr) end
 
@@ -1641,8 +1651,8 @@ function vim.fn.execute(command, silent) end
 --- Returns empty string otherwise.
 --- If {expr} starts with "./" the |current-directory| is used.
 ---
---- @param expr any
---- @return any
+--- @param expr string
+--- @return string
 function vim.fn.exepath(expr) end
 
 --- The result is a Number, which is |TRUE| if {expr} is
@@ -1733,7 +1743,7 @@ function vim.fn.exepath(expr) end
 --- <This doesn't check for existence of the "bufcount" variable,
 --- but gets the value of "bufcount", and checks if that exists.
 ---
---- @param expr any
+--- @param expr string
 --- @return 0|1
 function vim.fn.exists(expr) end
 
@@ -1747,7 +1757,7 @@ function vim.fn.exists(expr) end
 ---   echo exp(-1)
 --- <  0.367879
 ---
---- @param expr any
+--- @param expr number
 --- @return any
 function vim.fn.exp(expr) end
 
@@ -1916,9 +1926,9 @@ function vim.fn.expandcmd(string, options) end
 --- fails.
 --- Returns {expr1}.  Returns 0 on error.
 ---
---- @param expr1 any
---- @param expr2 any
---- @param expr3? any
+--- @param expr1 table
+--- @param expr2 table
+--- @param expr3? table
 --- @return any
 function vim.fn.extend(expr1, expr2, expr3) end
 
@@ -1926,9 +1936,9 @@ function vim.fn.extend(expr1, expr2, expr3) end
 --- List or Dictionary is created and returned.  {expr1} remains
 --- unchanged.
 ---
---- @param expr1 any
---- @param expr2 any
---- @param expr3? any
+--- @param expr1 table
+--- @param expr2 table
+--- @param expr3? table
 --- @return any
 function vim.fn.extendnew(expr1, expr2, expr3) end
 
@@ -1989,6 +1999,19 @@ function vim.fn.feedkeys(string, mode) end
 --- @return any
 function vim.fn.file_readable(file) end
 
+--- Copy the file pointed to by the name {from} to {to}. The
+--- result is a Number, which is |TRUE| if the file was copied
+--- successfully, and |FALSE| when it failed.
+--- If a file with name {to} already exists, it will fail.
+--- Note that it does not handle directories (yet).
+---
+--- This function is not available in the |sandbox|.
+---
+--- @param from string
+--- @param to string
+--- @return 0|1
+function vim.fn.filecopy(from, to) end
+
 --- The result is a Number, which is |TRUE| when a file with the
 --- name {file} exists, and can be read.  If {file} doesn't exist,
 --- or is a directory, the result is |FALSE|.  {file} is any
@@ -2070,8 +2093,8 @@ function vim.fn.filewritable(file) end
 --- When {expr2} is a Funcref errors inside a function are ignored,
 --- unless it was defined with the "abort" flag.
 ---
---- @param expr1 any
---- @param expr2 any
+--- @param expr1 string|table
+--- @param expr2 string|function
 --- @return any
 function vim.fn.filter(expr1, expr2) end
 
@@ -2094,7 +2117,7 @@ function vim.fn.filter(expr1, expr2) end
 ---
 --- @param name string
 --- @param path? string
---- @param count? any
+--- @param count? integer
 --- @return any
 function vim.fn.finddir(name, path, count) end
 
@@ -2129,15 +2152,15 @@ function vim.fn.findfile(name, path, count) end
 ---   echo flatten([1, [2, [3, 4]], 5], 1)
 --- <  [1, 2, [3, 4], 5]
 ---
---- @param list any
---- @param maxdepth? any
+--- @param list any[]
+--- @param maxdepth? integer
 --- @return any[]|0
 function vim.fn.flatten(list, maxdepth) end
 
 --- Like |flatten()| but first make a copy of {list}.
 ---
---- @param list any
---- @param maxdepth? any
+--- @param list any[]
+--- @param maxdepth? integer
 --- @return any[]|0
 function vim.fn.flattennew(list, maxdepth) end
 
@@ -2162,7 +2185,7 @@ function vim.fn.flattennew(list, maxdepth) end
 ---   echo float2nr(1.0e-100)
 --- <  0
 ---
---- @param expr any
+--- @param expr number
 --- @return any
 function vim.fn.float2nr(expr) end
 
@@ -2178,7 +2201,7 @@ function vim.fn.float2nr(expr) end
 ---   echo floor(4.0)
 --- <  4.0
 ---
---- @param expr any
+--- @param expr number
 --- @return any
 function vim.fn.floor(expr) end
 
@@ -2197,8 +2220,8 @@ function vim.fn.floor(expr) end
 ---   echo fmod(-12.33, 1.22)
 --- <  -0.13
 ---
---- @param expr1 any
---- @param expr2 any
+--- @param expr1 number
+--- @param expr2 number
 --- @return any
 function vim.fn.fmod(expr1, expr2) end
 
@@ -2343,8 +2366,8 @@ function vim.fn.foldtextresult(lnum) end
 --- When {expr2} is a Funcref errors inside a function are ignored,
 --- unless it was defined with the "abort" flag.
 ---
---- @param expr1 any
---- @param expr2 any
+--- @param expr1 string|table
+--- @param expr2 string|function
 --- @return any
 function vim.fn.foreach(expr1, expr2) end
 
@@ -2486,7 +2509,7 @@ vim.fn['function'] = function(name, arglist, dict) end
 --- it's safe to perform.  This is when waiting for the user to
 --- type a character.
 ---
---- @param atexit? any
+--- @param atexit? boolean
 --- @return any
 function vim.fn.garbagecollect(atexit) end
 
@@ -2523,12 +2546,25 @@ function vim.fn.get(blob, idx, default) end
 --- @return any
 function vim.fn.get(dict, key, default) end
 
---- Get item {what} from Funcref {func}.  Possible values for
+--- Get item {what} from |Funcref| {func}.  Possible values for
 --- {what} are:
----   "name"  The function name
----   "func"  The function
----   "dict"  The dictionary
----   "args"  The list with arguments
+---   "name"    The function name
+---   "func"    The function
+---   "dict"    The dictionary
+---   "args"    The list with arguments
+---   "arity"   A dictionary with information about the number of
+---       arguments accepted by the function (minus the
+---       {arglist}) with the following fields:
+---     required    the number of positional arguments
+---     optional    the number of optional arguments,
+---           in addition to the required ones
+---     varargs     |TRUE| if the function accepts a
+---           variable number of arguments |...|
+---
+---     Note: There is no error, if the {arglist} of
+---     the Funcref contains more arguments than the
+---     Funcref expects, it's not validated.
+---
 --- Returns zero on error.
 ---
 --- @param func function
@@ -2634,8 +2670,9 @@ function vim.fn.getbufinfo(dict) end
 ---
 --- Example: >vim
 ---   let lines = getbufline(bufnr("myfile"), 1, "$")
+--- <
 ---
---- @param buf any
+--- @param buf integer|string
 --- @param lnum integer
 --- @param end_? integer
 --- @return any
@@ -2669,7 +2706,7 @@ function vim.fn.getbufoneline(buf, lnum) end
 ---   let bufmodified = getbufvar(1, "&mod")
 ---   echo "todo myvar = " .. getbufvar("todo", "myvar")
 ---
---- @param buf any
+--- @param buf integer|string
 --- @param varname string
 --- @param def? any
 --- @return any
@@ -2766,8 +2803,9 @@ function vim.fn.getchangelist(buf) end
 ---   endfunction
 --- <
 ---
+--- @param expr? 0|1
 --- @return integer
-function vim.fn.getchar() end
+function vim.fn.getchar(expr) end
 
 --- The result is a Number which is the state of the modifiers for
 --- the last obtained character with getchar() or in another way.
@@ -2800,7 +2838,7 @@ function vim.fn.getcharmod() end
 ---   getpos('.')    returns [0, 5, 7, 0]
 --- <
 ---
---- @param expr any
+--- @param expr string
 --- @return integer[]
 function vim.fn.getcharpos(expr) end
 
@@ -2823,7 +2861,7 @@ function vim.fn.getcharpos(expr) end
 ---   nnoremap <expr> , getcharsearch().forward ? ',' : ';'
 --- <Also see |setcharsearch()|.
 ---
---- @return table[]
+--- @return table
 function vim.fn.getcharsearch() end
 
 --- Get a single character from the user or input stream as a
@@ -2837,27 +2875,28 @@ function vim.fn.getcharsearch() end
 --- Otherwise this works like |getchar()|, except that a number
 --- result is converted to a string.
 ---
+--- @param expr? 0|1
 --- @return string
-function vim.fn.getcharstr() end
+function vim.fn.getcharstr(expr) end
 
 --- Return the type of the current command-line completion.
 --- Only works when the command line is being edited, thus
 --- requires use of |c_CTRL-\_e| or |c_CTRL-R_=|.
 --- See |:command-completion| for the return string.
---- Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()| and
---- |setcmdline()|.
+--- Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()|,
+--- |getcmdprompt()| and |setcmdline()|.
 --- Returns an empty string when completion is not defined.
 ---
 --- @return string
 function vim.fn.getcmdcompltype() end
 
---- Return the current command-line.  Only works when the command
---- line is being edited, thus requires use of |c_CTRL-\_e| or
---- |c_CTRL-R_=|.
+--- Return the current command-line input.  Only works when the
+--- command line is being edited, thus requires use of
+--- |c_CTRL-\_e| or |c_CTRL-R_=|.
 --- Example: >vim
 ---   cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
---- <Also see |getcmdtype()|, |getcmdpos()|, |setcmdpos()| and
---- |setcmdline()|.
+--- <Also see |getcmdtype()|, |getcmdpos()|, |setcmdpos()|,
+--- |getcmdprompt()| and |setcmdline()|.
 --- Returns an empty string when entering a password or using
 --- |inputsecret()|.
 ---
@@ -2869,12 +2908,22 @@ function vim.fn.getcmdline() end
 --- Only works when editing the command line, thus requires use of
 --- |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
 --- Returns 0 otherwise.
---- Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()| and
---- |setcmdline()|.
+--- Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()|,
+--- |getcmdprompt()| and |setcmdline()|.
 ---
 --- @return integer
 function vim.fn.getcmdpos() end
 
+--- Return the current command-line prompt when using functions
+--- like |input()| or |confirm()|.
+--- Only works when the command line is being edited, thus
+--- requires use of |c_CTRL-\_e| or |c_CTRL-R_=|.
+--- Also see |getcmdtype()|, |getcmdline()|, |getcmdpos()|,
+--- |setcmdpos()| and |setcmdline()|.
+---
+--- @return string
+function vim.fn.getcmdprompt() end
+
 --- Return the screen position of the cursor in the command line
 --- as a byte count.  The first column is 1.
 --- Instead of |getcmdpos()|, it adds the prompt position.
@@ -2927,6 +2976,7 @@ function vim.fn.getcmdwintype() end
 --- customlist,{func} custom completion, defined via {func}
 --- diff_buffer  |:diffget| and |:diffput| completion
 --- dir    directory names
+--- dir_in_path  directory names in |'cdpath'|
 --- environment  environment variable names
 --- event    autocommand events
 --- expression  Vim expression
@@ -2979,9 +3029,9 @@ function vim.fn.getcmdwintype() end
 --- If there are no matches, an empty list is returned.  An
 --- invalid value for {type} produces an error.
 ---
---- @param pat any
---- @param type any
---- @param filtered? any
+--- @param pat string
+--- @param type string
+--- @param filtered? boolean
 --- @return string[]
 function vim.fn.getcompletion(pat, type, filtered) end
 
@@ -3227,7 +3277,7 @@ function vim.fn.getline(lnum, end_) end
 --- <
 ---
 --- @param nr integer
---- @param what? any
+--- @param what? table
 --- @return any
 function vim.fn.getloclist(nr, what) end
 
@@ -3249,8 +3299,8 @@ function vim.fn.getloclist(nr, what) end
 --- Refer to |getpos()| for getting information about a specific
 --- mark.
 ---
---- @param buf? any
---- @return any
+--- @param buf? integer?
+--- @return vim.fn.getmarklist.ret.item[]
 function vim.fn.getmarklist(buf) end
 
 --- Returns a |List| with all matches previously defined for the
@@ -3284,7 +3334,7 @@ function vim.fn.getmarklist(buf) end
 ---   unlet m
 --- <
 ---
---- @param win? any
+--- @param win? integer
 --- @return any
 function vim.fn.getmatches(win) end
 
@@ -3327,9 +3377,34 @@ function vim.fn.getmousepos() end
 --- @return integer
 function vim.fn.getpid() end
 
---- Get the position for String {expr}.  For possible values of
---- {expr} see |line()|.  For getting the cursor position see
---- |getcurpos()|.
+--- Get the position for String {expr}.
+--- The accepted values for {expr} are:
+---     .      The cursor position.
+---     $      The last line in the current buffer.
+---     'x      Position of mark x (if the mark is not set, 0 is
+---       returned for all values).
+---     w0      First line visible in current window (one if the
+---       display isn't updated, e.g. in silent Ex mode).
+---     w$      Last line visible in current window (this is one
+---       less than "w0" if no lines are visible).
+---     v      When not in Visual mode, returns the cursor
+---       position.  In Visual mode, returns the other end
+---       of the Visual area.  A good way to think about
+---       this is that in Visual mode "v" and "." complement
+---       each other.  While "." refers to the cursor
+---       position, "v" refers to where |v_o| would move the
+---       cursor.  As a result, you can use "v" and "."
+---       together to work on all of a selection in
+---       characterwise Visual mode.  If the cursor is at
+---       the end of a characterwise Visual area, "v" refers
+---       to the start of the same Visual area.  And if the
+---       cursor is at the start of a characterwise Visual
+---       area, "v" refers to the end of the same Visual
+---       area.  "v" differs from |'<| and |'>| in that it's
+---       updated right away.
+--- Note that a mark in another file can be used.  The line number
+--- then applies to another buffer.
+---
 --- The result is a |List| with four numbers:
 ---     [bufnum, lnum, col, off]
 --- "bufnum" is zero, unless a mark like '0 or 'A is used, then it
@@ -3340,20 +3415,25 @@ function vim.fn.getpid() end
 --- it is the offset in screen columns from the start of the
 --- character.  E.g., a position within a <Tab> or after the last
 --- character.
---- Note that for '< and '> Visual mode matters: when it is "V"
---- (visual line mode) the column of '< is zero and the column of
---- '> is a large number equal to |v:maxcol|.
+---
+--- For getting the cursor position see |getcurpos()|.
 --- The column number in the returned List is the byte position
 --- within the line. To get the character position in the line,
 --- use |getcharpos()|.
+---
+--- Note that for '< and '> Visual mode matters: when it is "V"
+--- (visual line mode) the column of '< is zero and the column of
+--- '> is a large number equal to |v:maxcol|.
 --- A very large column number equal to |v:maxcol| can be returned,
 --- in which case it means "after the end of the line".
 --- If {expr} is invalid, returns a list with all zeros.
+---
 --- This can be used to save and restore the position of a mark: >vim
 ---   let save_a_mark = getpos("'a")
 ---   " ...
 ---   call setpos("'a", save_a_mark)
---- <Also see |getcharpos()|, |getcurpos()| and |setpos()|.
+--- <
+--- Also see |getcharpos()|, |getcurpos()| and |setpos()|.
 ---
 --- @param expr string
 --- @return integer[]
@@ -3462,7 +3542,7 @@ function vim.fn.getpos(expr) end
 ---   echo getqflist({'lines' : ["F1:10:L10"]})
 --- <
 ---
---- @param what? any
+--- @param what? table
 --- @return any
 function vim.fn.getqflist(what) end
 
@@ -3536,14 +3616,14 @@ function vim.fn.getreginfo(regname) end
 --- The optional argument {opts} is a Dict and supports the
 --- following items:
 ---
----   type    Specify the region's selection type
----       (default: "v"):
----       "v"    for |charwise| mode
----       "V"    for |linewise| mode
----       "<CTRL-V>"  for |blockwise-visual| mode
+---   type    Specify the region's selection type.
+---       See |getregtype()| for possible values,
+---       except that the width can be omitted
+---       and an empty string cannot be used.
+---       (default: "v")
 ---
 ---   exclusive  If |TRUE|, use exclusive selection
----       for the end position
+---       for the end position.
 ---       (default: follow 'selection')
 ---
 --- You can get the last selection type by |visualmode()|.
@@ -3569,8 +3649,8 @@ function vim.fn.getreginfo(regname) end
 ---   difference if the buffer is displayed in a window with
 ---   different 'virtualedit' or 'list' values.
 ---
---- Examples: >
----   :xnoremap <CR>
+--- Examples: >vim
+---   xnoremap <CR>
 ---   \ <Cmd>echom getregion(
 ---   \ getpos('v'), getpos('.'), #{ type: mode() })<CR>
 --- <
@@ -3777,7 +3857,7 @@ function vim.fn.gettagstack(winnr) end
 --- xgettext does not understand escaping in single quoted
 --- strings.
 ---
---- @param text any
+--- @param text string
 --- @return any
 function vim.fn.gettext(text) end
 
@@ -3904,10 +3984,10 @@ function vim.fn.getwinvar(winnr, varname, def) end
 --- See |expand()| for expanding special Vim variables.  See
 --- |system()| for getting the raw output of an external command.
 ---
---- @param expr any
+--- @param expr string
 --- @param nosuf? boolean
---- @param list? any
---- @param alllinks? any
+--- @param list? boolean
+--- @param alllinks? boolean
 --- @return any
 function vim.fn.glob(expr, nosuf, list, alllinks) end
 
@@ -3965,10 +4045,10 @@ function vim.fn.glob2regpat(string) end
 --- supported, thus using 'path' will not always work properly.
 ---
 --- @param path string
---- @param expr any
+--- @param expr string
 --- @param nosuf? boolean
---- @param list? any
---- @param allinks? any
+--- @param list? boolean
+--- @param allinks? boolean
 --- @return any
 function vim.fn.globpath(path, expr, nosuf, list, allinks) end
 
@@ -4039,7 +4119,7 @@ function vim.fn.globpath(path, expr, nosuf, list, allinks) end
 ---   endif
 --- <
 ---
---- @param feature any
+--- @param feature string
 --- @return 0|1
 function vim.fn.has(feature) end
 
@@ -4047,8 +4127,8 @@ function vim.fn.has(feature) end
 --- has an entry with key {key}.  FALSE otherwise. The {key}
 --- argument is a string.
 ---
---- @param dict any
---- @param key any
+--- @param dict table
+--- @param key string
 --- @return 0|1
 function vim.fn.has_key(dict, key) end
 
@@ -4105,7 +4185,7 @@ function vim.fn.haslocaldir(winnr, tabnr) end
 ---
 --- @param what any
 --- @param mode? string
---- @param abbr? any
+--- @param abbr? boolean
 --- @return 0|1
 function vim.fn.hasmapto(what, mode, abbr) end
 
@@ -4143,7 +4223,7 @@ function vim.fn.highlight_exists(name) end
 ---   let date=input("Enter date: ")
 --- <This function is not available in the |sandbox|.
 ---
---- @param history any
+--- @param history string
 --- @param item any
 --- @return 0|1
 function vim.fn.histadd(history, item) end
@@ -4180,7 +4260,7 @@ function vim.fn.histadd(history, item) end
 ---   let \@/ = histget("search", -1)
 --- <
 ---
---- @param history any
+--- @param history string
 --- @param item? any
 --- @return 0|1
 function vim.fn.histdel(history, item) end
@@ -4200,8 +4280,8 @@ function vim.fn.histdel(history, item) end
 ---   command -nargs=1 H execute histget("cmd", 0+<args>)
 --- <
 ---
---- @param history any
---- @param index? any
+--- @param history string
+--- @param index? integer|string
 --- @return string
 function vim.fn.histget(history, index) end
 
@@ -4211,8 +4291,9 @@ function vim.fn.histget(history, index) end
 ---
 --- Example: >vim
 ---   let inp_index = histnr("expr")
+--- <
 ---
---- @param history any
+--- @param history string
 --- @return integer
 function vim.fn.histnr(history) end
 
@@ -4258,8 +4339,8 @@ function vim.fn.hostname() end
 --- cannot use UCS-2 in a string anyway, because of the NUL bytes.
 ---
 --- @param string string
---- @param from any
---- @param to any
+--- @param from string
+--- @param to string
 --- @return any
 function vim.fn.iconv(string, from, to) end
 
@@ -4270,7 +4351,7 @@ function vim.fn.iconv(string, from, to) end
 --- Note that `v:_null_string`, `v:_null_list`, `v:_null_dict` and
 --- `v:_null_blob` have the same `id()` with different types
 --- because they are internally represented as NULL pointers.
---- `id()` returns a hexadecimal representanion of the pointers to
+--- `id()` returns a hexadecimal representation of the pointers to
 --- the containers (i.e. like `0x994a40`), same as `printf("%p",
 --- {expr})`, but it is advised against counting on the exact
 --- format of the return value.
@@ -4318,11 +4399,12 @@ function vim.fn.indent(lnum) end
 ---   if index(numbers, 123) >= 0
 ---     " ...
 ---   endif
+--- <
 ---
 --- @param object any
 --- @param expr any
---- @param start? any
---- @param ic? any
+--- @param start? integer
+--- @param ic? boolean
 --- @return any
 function vim.fn.index(object, expr, start, ic) end
 
@@ -4362,6 +4444,7 @@ function vim.fn.index(object, expr, start, ic) end
 ---   echo indexof(l, "v:val.n == 20")
 ---   echo indexof(l, {i, v -> v.n == 30})
 ---   echo indexof(l, "v:val.n == 20", #{startidx: 1})
+--- <
 ---
 --- @param object any
 --- @param expr any
@@ -4370,9 +4453,9 @@ function vim.fn.index(object, expr, start, ic) end
 function vim.fn.indexof(object, expr, opts) end
 
 ---
---- @param prompt any
---- @param text? any
---- @param completion? any
+--- @param prompt string
+--- @param text? string
+--- @param completion? string
 --- @return any
 function vim.fn.input(prompt, text, completion) end
 
@@ -4484,6 +4567,7 @@ function vim.fn.input(prompt, text, completion) end
 ---     let g:Foo = input("enter search pattern: ")
 ---     call inputrestore()
 ---   endfunction
+--- <
 ---
 --- @param opts table
 --- @return any
@@ -4512,7 +4596,7 @@ function vim.fn.inputdialog(...) end
 ---   let color = inputlist(['Select color:', '1. red',
 ---     \ '2. green', '3. blue'])
 ---
---- @param textlist any
+--- @param textlist string[]
 --- @return any
 function vim.fn.inputlist(textlist) end
 
@@ -4544,8 +4628,8 @@ function vim.fn.inputsave() end
 --- typed on the command-line in response to the issued prompt.
 --- NOTE: Command-line completion is not supported.
 ---
---- @param prompt any
---- @param text? any
+--- @param prompt string
+--- @param text? string
 --- @return any
 function vim.fn.inputsecret(prompt, text) end
 
@@ -4592,16 +4676,34 @@ function vim.fn.interrupt() end
 ---   let bits = invert(bits)
 --- <
 ---
---- @param expr any
+--- @param expr number
 --- @return any
 function vim.fn.invert(expr) end
 
+--- The result is a Number, which is |TRUE| when {path} is an
+--- absolute path.
+--- On Unix, a path is considered absolute when it starts with '/'.
+--- On MS-Windows, it is considered absolute when it starts with an
+--- optional drive prefix and is followed by a '\' or '/'. UNC paths
+--- are always absolute.
+--- Example: >vim
+---   echo isabsolutepath('/usr/share/')  " 1
+---   echo isabsolutepath('./foobar')    " 0
+---   echo isabsolutepath('C:\Windows')  " 1
+---   echo isabsolutepath('foobar')    " 0
+---   echo isabsolutepath('\\remote\file')  " 1
+--- <
+---
+--- @param path string
+--- @return 0|1
+function vim.fn.isabsolutepath(path) end
+
 --- The result is a Number, which is |TRUE| when a directory
 --- with the name {directory} exists.  If {directory} doesn't
 --- exist, or isn't a directory, the result is |FALSE|.  {directory}
 --- is any expression, which is used as a String.
 ---
---- @param directory any
+--- @param directory string
 --- @return 0|1
 function vim.fn.isdirectory(directory) end
 
@@ -4612,7 +4714,7 @@ function vim.fn.isdirectory(directory) end
 ---   echo isinf(-1.0 / 0.0)
 --- <  -1
 ---
---- @param expr any
+--- @param expr number
 --- @return 1|0|-1
 function vim.fn.isinf(expr) end
 
@@ -4637,7 +4739,7 @@ function vim.fn.islocked(expr) end
 ---   echo isnan(0.0 / 0.0)
 --- <  1
 ---
---- @param expr any
+--- @param expr number
 --- @return 0|1
 function vim.fn.isnan(expr) end
 
@@ -4649,6 +4751,10 @@ function vim.fn.isnan(expr) end
 ---   for [key, value] in items(mydict)
 ---      echo key .. ': ' .. value
 ---   endfor
+--- <
+--- A List or a String argument is also supported.  In these
+--- cases, items() returns a List with the index and the value at
+--- the index.
 ---
 --- @param dict any
 --- @return any
@@ -4663,7 +4769,7 @@ function vim.fn.jobclose(...) end
 
 --- Return the PID (process id) of |job-id| {job}.
 ---
---- @param job any
+--- @param job integer
 --- @return integer
 function vim.fn.jobpid(job) end
 
@@ -4671,7 +4777,7 @@ function vim.fn.jobpid(job) end
 --- columns and {height} rows.
 --- Fails if the job was not started with `"pty":v:true`.
 ---
---- @param job any
+--- @param job integer
 --- @param width integer
 --- @param height integer
 --- @return any
@@ -4769,7 +4875,7 @@ function vim.fn.jobsend(...) end
 ---   - -1 if {cmd}[0] is not executable.
 --- See also |job-control|, |channel|, |msgpack-rpc|.
 ---
---- @param cmd any
+--- @param cmd string|string[]
 --- @param opts? table
 --- @return any
 function vim.fn.jobstart(cmd, opts) end
@@ -4783,7 +4889,7 @@ function vim.fn.jobstart(cmd, opts) end
 --- Returns 1 for valid job id, 0 for invalid id, including jobs have
 --- exited or stopped.
 ---
---- @param id any
+--- @param id integer
 --- @return any
 function vim.fn.jobstop(id) end
 
@@ -4807,7 +4913,7 @@ function vim.fn.jobstop(id) end
 ---   -2 if the job was interrupted (by |CTRL-C|)
 ---   -3 if the job-id is invalid
 ---
---- @param jobs any
+--- @param jobs integer[]
 --- @param timeout? integer
 --- @return any
 function vim.fn.jobwait(jobs, timeout) end
@@ -4822,8 +4928,8 @@ function vim.fn.jobwait(jobs, timeout) end
 --- converted into a string like with |string()|.
 --- The opposite function is |split()|.
 ---
---- @param list any
---- @param sep? any
+--- @param list any[]
+--- @param sep? string
 --- @return any
 function vim.fn.join(list, sep) end
 
@@ -4863,7 +4969,7 @@ function vim.fn.json_encode(expr) end
 --- Return a |List| with all the keys of {dict}.  The |List| is in
 --- arbitrary order.  Also see |items()| and |values()|.
 ---
---- @param dict any
+--- @param dict table
 --- @return any
 function vim.fn.keys(dict) end
 
@@ -4958,28 +5064,16 @@ function vim.fn.libcall(libname, funcname, argument) end
 --- @return any
 function vim.fn.libcallnr(libname, funcname, argument) end
 
---- The result is a Number, which is the line number of the file
---- position given with {expr}.  The {expr} argument is a string.
---- The accepted positions are:
----     .      the cursor position
----     $      the last line in the current buffer
----     'x      position of mark x (if the mark is not set, 0 is
----       returned)
----     w0      first line visible in current window (one if the
----       display isn't updated, e.g. in silent Ex mode)
----     w$      last line visible in current window (this is one
----       less than "w0" if no lines are visible)
----     v      In Visual mode: the start of the Visual area (the
----       cursor is the end).  When not in Visual mode
----       returns the cursor position.  Differs from |'<| in
----       that it's updated right away.
---- Note that a mark in another file can be used.  The line number
---- then applies to another buffer.
+--- See |getpos()| for accepted positions.
+---
 --- To get the column number use |col()|.  To get both use
 --- |getpos()|.
+---
 --- With the optional {winid} argument the values are obtained for
 --- that window instead of the current window.
+---
 --- Returns 0 for invalid values of {expr} and {winid}.
+---
 --- Examples: >vim
 ---   echo line(".")      " line number of the cursor
 ---   echo line(".", winid)    " idem, in window "winid"
@@ -4989,7 +5083,7 @@ function vim.fn.libcallnr(libname, funcname, argument) end
 --- To jump to the last known position when opening a file see
 --- |last-position-jump|.
 ---
---- @param expr any
+--- @param expr string|integer[]
 --- @param winid? integer
 --- @return integer
 function vim.fn.line(expr, winid) end
@@ -5029,7 +5123,7 @@ function vim.fn.lispindent(lnum) end
 ---
 --- |blob2list()| does the opposite.
 ---
---- @param list any
+--- @param list any[]
 --- @return any
 function vim.fn.list2blob(list) end
 
@@ -5048,8 +5142,8 @@ function vim.fn.list2blob(list) end
 --- <
 --- Returns an empty string on error.
 ---
---- @param list any
---- @param utf8? any
+--- @param list any[]
+--- @param utf8? boolean
 --- @return any
 function vim.fn.list2str(list, utf8) end
 
@@ -5069,7 +5163,7 @@ function vim.fn.localtime() end
 ---   echo log(exp(5))
 --- <  5.0
 ---
---- @param expr any
+--- @param expr number
 --- @return any
 function vim.fn.log(expr) end
 
@@ -5082,7 +5176,7 @@ function vim.fn.log(expr) end
 ---   echo log10(0.01)
 --- <  -2.0
 ---
---- @param expr any
+--- @param expr number
 --- @return any
 function vim.fn.log10(expr) end
 
@@ -5139,8 +5233,8 @@ function vim.fn.log10(expr) end
 --- When {expr2} is a Funcref errors inside a function are ignored,
 --- unless it was defined with the "abort" flag.
 ---
---- @param expr1 any
---- @param expr2 any
+--- @param expr1 string|table|any[]
+--- @param expr2 string|function
 --- @return any
 function vim.fn.map(expr1, expr2) end
 
@@ -5182,6 +5276,7 @@ function vim.fn.map(expr1, expr2) end
 ---   "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate
 ---         form, only present when it differs from "lhsraw"
 ---   "rhs"       The {rhs} of the mapping as typed.
+---   "callback" Lua function, if RHS was defined as such.
 ---   "silent"   1 for a |:map-silent| mapping, else 0.
 ---   "noremap"  1 if the {rhs} of the mapping is not remappable.
 ---   "script"   1 if mapping was defined with <script>.
@@ -5214,6 +5309,7 @@ function vim.fn.map(expr1, expr2) end
 --- This function can be used to map a key even when it's already
 --- mapped, and have it do the original mapping too.  Sketch: >vim
 ---   exe 'nnoremap <Tab> ==' .. maparg('<Tab>', 'n')
+--- <
 ---
 --- @param name string
 --- @param mode? string
@@ -5263,7 +5359,7 @@ function vim.fn.maparg(name, mode, abbr, dict) end
 ---
 --- @param name string
 --- @param mode? string
---- @param abbr? any
+--- @param abbr? boolean
 --- @return any
 function vim.fn.mapcheck(name, mode, abbr) end
 
@@ -5296,9 +5392,11 @@ function vim.fn.mapcheck(name, mode, abbr) end
 ---       \ {_, m -> m.lhs == 'xyzzy'})[0].mode_bits
 ---   ounmap xyzzy
 ---   echo printf("Operator-pending mode bit: 0x%x", op_bit)
+--- <
 ---
---- @return any
-function vim.fn.maplist() end
+--- @param abbr? 0|1
+--- @return table[]
+function vim.fn.maplist(abbr) end
 
 --- Like |map()| but instead of replacing items in {expr1} a new
 --- List or Dictionary is created and returned.  {expr1} remains
@@ -5311,8 +5409,8 @@ function vim.fn.maplist() end
 function vim.fn.mapnew(expr1, expr2) end
 
 --- @param mode string
---- @param abbr? any
---- @param dict? any
+--- @param abbr? boolean
+--- @param dict? boolean
 --- @return any
 function vim.fn.mapset(mode, abbr, dict) end
 
@@ -5350,8 +5448,9 @@ function vim.fn.mapset(mode, abbr, dict) end
 ---   for d in save_maps
 ---       call mapset(d)
 ---   endfor
+--- <
 ---
---- @param dict any
+--- @param dict boolean
 --- @return any
 function vim.fn.mapset(dict) end
 
@@ -5417,10 +5516,10 @@ function vim.fn.mapset(dict) end
 --- zero matches at the start instead of a number of matches
 --- further down in the text.
 ---
---- @param expr any
---- @param pat any
---- @param start? any
---- @param count? any
+--- @param expr string|any[]
+--- @param pat string
+--- @param start? integer
+--- @param count? integer
 --- @return any
 function vim.fn.match(expr, pat, start, count) end
 
@@ -5481,20 +5580,20 @@ function vim.fn.match(expr, pat, start, count) end
 --- available from |getmatches()|.  All matches can be deleted in
 --- one operation by |clearmatches()|.
 ---
---- @param group any
---- @param pattern any
---- @param priority? any
---- @param id? any
---- @param dict? any
+--- @param group integer|string
+--- @param pattern string
+--- @param priority? integer
+--- @param id? integer
+--- @param dict? string
 --- @return any
 function vim.fn.matchadd(group, pattern, priority, id, dict) end
 
 --- Same as |matchadd()|, but requires a list of positions {pos}
 --- instead of a pattern. This command is faster than |matchadd()|
---- because it does not require to handle regular expressions and
---- sets buffer line boundaries to redraw screen. It is supposed
---- to be used when fast match additions and deletions are
---- required, for example to highlight matching parentheses.
+--- because it does not handle regular expressions and it sets
+--- buffer line boundaries to redraw screen. It is supposed to be
+--- used when fast match additions and deletions are required, for
+--- example to highlight matching parentheses.
 ---           *E5030* *E5031*
 --- {pos} is a list of positions.  Each position can be one of
 --- these:
@@ -5525,11 +5624,11 @@ function vim.fn.matchadd(group, pattern, priority, id, dict) end
 --- <Matches added by |matchaddpos()| are returned by
 --- |getmatches()|.
 ---
---- @param group any
---- @param pos any
---- @param priority? any
---- @param id? any
---- @param dict? any
+--- @param group integer|string
+--- @param pos any[]
+--- @param priority? integer
+--- @param id? integer
+--- @param dict? string
 --- @return any
 function vim.fn.matchaddpos(group, pos, priority, id, dict) end
 
@@ -5575,19 +5674,19 @@ function vim.fn.matcharg(nr) end
 ---
 --- Examples: >vim
 ---     " Assuming line 3 in buffer 5 contains "a"
----     :echo matchbufline(5, '\<\k\+\>', 3, 3)
----     [{'lnum': 3, 'byteidx': 0, 'text': 'a'}]
+---     echo matchbufline(5, '\<\k\+\>', 3, 3)
+--- <    `[{'lnum': 3, 'byteidx': 0, 'text': 'a'}]` >vim
 ---     " Assuming line 4 in buffer 10 contains "tik tok"
----     :echo matchbufline(10, '\<\k\+\>', 1, 4)
----     [{'lnum': 4, 'byteidx': 0, 'text': 'tik'}, {'lnum': 4, 'byteidx': 4, 'text': 'tok'}]
---- <
+---     echo matchbufline(10, '\<\k\+\>', 1, 4)
+--- <    `[{'lnum': 4, 'byteidx': 0, 'text': 'tik'}, {'lnum': 4, 'byteidx': 4, 'text': 'tok'}]`
+---
 --- If {submatch} is present and is v:true, then submatches like
 --- "\1", "\2", etc. are also returned.  Example: >vim
 ---     " Assuming line 2 in buffer 2 contains "acd"
----     :echo matchbufline(2, '\(a\)\?\(b\)\?\(c\)\?\(.*\)', 2, 2
+---     echo matchbufline(2, '\(a\)\?\(b\)\?\(c\)\?\(.*\)', 2, 2
 ---         \ {'submatches': v:true})
----     [{'lnum': 2, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}]
---- <The "submatches" List always contains 9 items.  If a submatch
+--- <    `[{'lnum': 2, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}]`
+--- The "submatches" List always contains 9 items.  If a submatch
 --- is not found, then an empty string is returned for that
 --- submatch.
 ---
@@ -5606,8 +5705,8 @@ function vim.fn.matchbufline(buf, pat, lnum, end_, dict) end
 --- If {win} is specified, use the window with this number or
 --- window ID instead of the current window.
 ---
---- @param id any
---- @param win? any
+--- @param id integer
+--- @param win? integer
 --- @return any
 function vim.fn.matchdelete(id, win) end
 
@@ -5630,9 +5729,9 @@ function vim.fn.matchdelete(id, win) end
 --- When {expr} is a |List| the result is equal to |match()|.
 ---
 --- @param expr any
---- @param pat any
---- @param start? any
---- @param count? any
+--- @param pat string
+--- @param start? integer
+--- @param count? integer
 --- @return any
 function vim.fn.matchend(expr, pat, start, count) end
 
@@ -5698,9 +5797,9 @@ function vim.fn.matchend(expr, pat, start, count) end
 ---         \ {'matchseq': 1})
 --- <results in `['two one']`.
 ---
---- @param list any
---- @param str any
---- @param dict? any
+--- @param list any[]
+--- @param str string
+--- @param dict? string
 --- @return any
 function vim.fn.matchfuzzy(list, str, dict) end
 
@@ -5725,9 +5824,9 @@ function vim.fn.matchfuzzy(list, str, dict) end
 ---     \ ->matchfuzzypos('ll', {'key' : 'text'})
 --- <results in `[[{"id": 10, "text": "hello"}], [[2, 3]], [127]]`
 ---
---- @param list any
---- @param str any
---- @param dict? any
+--- @param list any[]
+--- @param str string
+--- @param dict? string
 --- @return any
 function vim.fn.matchfuzzypos(list, str, dict) end
 
@@ -5743,9 +5842,9 @@ function vim.fn.matchfuzzypos(list, str, dict) end
 --- You can pass in a List, but that is not very useful.
 ---
 --- @param expr any
---- @param pat any
---- @param start? any
---- @param count? any
+--- @param pat string
+--- @param start? integer
+--- @param count? integer
 --- @return any
 function vim.fn.matchlist(expr, pat, start, count) end
 
@@ -5762,9 +5861,9 @@ function vim.fn.matchlist(expr, pat, start, count) end
 --- The type isn't changed, it's not necessarily a String.
 ---
 --- @param expr any
---- @param pat any
---- @param start? any
---- @param count? any
+--- @param pat string
+--- @param start? integer
+--- @param count? integer
 --- @return any
 function vim.fn.matchstr(expr, pat, start, count) end
 
@@ -5786,17 +5885,17 @@ function vim.fn.matchstr(expr, pat, start, count) end
 --- option settings on the pattern.
 ---
 --- Example: >vim
----     :echo matchstrlist(['tik tok'], '\<\k\+\>')
----     [{'idx': 0, 'byteidx': 0, 'text': 'tik'}, {'idx': 0, 'byteidx': 4, 'text': 'tok'}]
----     :echo matchstrlist(['a', 'b'], '\<\k\+\>')
----     [{'idx': 0, 'byteidx': 0, 'text': 'a'}, {'idx': 1, 'byteidx': 0, 'text': 'b'}]
---- <
+---     echo matchstrlist(['tik tok'], '\<\k\+\>')
+--- <    `[{'idx': 0, 'byteidx': 0, 'text': 'tik'}, {'idx': 0, 'byteidx': 4, 'text': 'tok'}]` >vim
+---     echo matchstrlist(['a', 'b'], '\<\k\+\>')
+--- <    `[{'idx': 0, 'byteidx': 0, 'text': 'a'}, {'idx': 1, 'byteidx': 0, 'text': 'b'}]`
+---
 --- If "submatches" is present and is v:true, then submatches like
 --- "\1", "\2", etc. are also returned.  Example: >vim
----     :echo matchstrlist(['acd'], '\(a\)\?\(b\)\?\(c\)\?\(.*\)',
+---     echo matchstrlist(['acd'], '\(a\)\?\(b\)\?\(c\)\?\(.*\)',
 ---         \ #{submatches: v:true})
----     [{'idx': 0, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}]
---- <The "submatches" List always contains 9 items.  If a submatch
+--- <    `[{'idx': 0, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}]`
+--- The "submatches" List always contains 9 items.  If a submatch
 --- is not found, then an empty string is returned for that
 --- submatch.
 ---
@@ -5824,9 +5923,9 @@ function vim.fn.matchstrlist(list, pat, dict) end
 --- The type isn't changed, it's not necessarily a String.
 ---
 --- @param expr any
---- @param pat any
---- @param start? any
---- @param count? any
+--- @param pat string
+--- @param start? integer
+--- @param count? integer
 --- @return any
 function vim.fn.matchstrpos(expr, pat, start, count) end
 
@@ -5889,7 +5988,7 @@ function vim.fn.max(expr) end
 --- <
 ---
 --- @param path string
---- @param modes? any
+--- @param modes? string
 --- @return any
 function vim.fn.menu_get(path, modes) end
 
@@ -5986,17 +6085,14 @@ function vim.fn.min(expr) end
 --- When {flags} is present it must be a string.  An empty string
 --- has no effect.
 ---
---- If {flags} contains "p" then intermediate directories are
---- created as necessary.
+--- {flags} can contain these character flags:
+---  "p"  intermediate directories will be created as necessary
+---  "D"  {name} will be deleted at the end of the current
+---   function, but not recursively |:defer|
+---  "R"  {name} will be deleted recursively at the end of the
+---   current function |:defer|
 ---
---- If {flags} contains "D" then {name} is deleted at the end of
---- the current function, as with: >vim
----   defer delete({name}, 'd')
---- <
---- If {flags} contains "R" then {name} is deleted recursively at
---- the end of the current function, as with: >vim
----   defer delete({name}, 'rf')
---- <Note that when {name} has more than one part and "p" is used
+--- Note that when {name} has more than one part and "p" is used
 --- some directories may already exist.  Only the first one that
 --- is created and what it contains is scheduled to be deleted.
 --- E.g. when using: >vim
@@ -6025,7 +6121,7 @@ function vim.fn.min(expr) end
 ---
 --- @param name string
 --- @param flags? string
---- @param prot? any
+--- @param prot? string
 --- @return any
 function vim.fn.mkdir(name, flags, prot) end
 
@@ -6159,12 +6255,7 @@ function vim.fn.msgpackdump(list, type) end
 ---      C parser does not support such values.
 --- float  |Float|. This value cannot possibly appear in
 ---   |msgpackparse()| output.
---- string  |readfile()|-style list of strings. This value will
----   appear in |msgpackparse()| output if string contains
----   zero byte or if string is a mapping key and mapping is
----   being represented as special dictionary for other
----   reasons.
---- binary  |String|, or |Blob| if binary string contains zero
+--- string  |String|, or |Blob| if binary string contains zero
 ---   byte. This value cannot appear in |msgpackparse()|
 ---   output since blobs were introduced.
 --- array  |List|. This value cannot appear in |msgpackparse()|
@@ -6211,8 +6302,8 @@ function vim.fn.nextnonblank(lnum) end
 --- characters.  nr2char(0) is a real NUL and terminates the
 --- string, thus results in an empty string.
 ---
---- @param expr any
---- @param utf8? any
+--- @param expr integer
+--- @param utf8? boolean
 --- @return any
 function vim.fn.nr2char(expr, utf8) end
 
@@ -6227,8 +6318,8 @@ function vim.fn.nr2char(expr, utf8) end
 --- to separate commands.  In many places it would not be clear if
 --- "|" is an operator or a command separator.
 ---
---- @param expr any
---- @param expr1 any
+--- @param expr number
+--- @param expr1 number
 --- @return any
 vim.fn['or'] = function(expr, expr1) end
 
@@ -6246,7 +6337,7 @@ vim.fn['or'] = function(expr, expr1) end
 --- Returns an empty string on error.
 ---
 --- @param path string
---- @param len? any
+--- @param len? integer
 --- @return any
 function vim.fn.pathshorten(path, len) end
 
@@ -6279,8 +6370,8 @@ function vim.fn.perleval(expr) end
 ---   echo pow(32, 0.20)
 --- <  2.0
 ---
---- @param x any
---- @param y any
+--- @param x number
+--- @param y number
 --- @return any
 function vim.fn.pow(x, y) end
 
@@ -6618,7 +6709,7 @@ function vim.fn.prevnonblank(lnum) end
 --- into this, copying the exact format string and parameters that
 --- were used.
 ---
---- @param fmt any
+--- @param fmt string
 --- @param expr1? any
 --- @return string
 function vim.fn.printf(fmt, expr1) end
@@ -6629,7 +6720,7 @@ function vim.fn.printf(fmt, expr1) end
 --- If the buffer doesn't exist or isn't a prompt buffer, an empty
 --- string is returned.
 ---
---- @param buf any
+--- @param buf integer|string
 --- @return any
 function vim.fn.prompt_getprompt(buf) end
 
@@ -6664,8 +6755,8 @@ function vim.fn.prompt_getprompt(buf) end
 ---    endfunc
 ---    call prompt_setcallback(bufnr(), function('s:TextEntered'))
 ---
---- @param buf any
---- @param expr any
+--- @param buf integer|string
+--- @param expr string|function
 --- @return any
 function vim.fn.prompt_setcallback(buf, expr) end
 
@@ -6677,8 +6768,8 @@ function vim.fn.prompt_setcallback(buf, expr) end
 --- mode.  Without setting a callback Vim will exit Insert mode,
 --- as in any buffer.
 ---
---- @param buf any
---- @param expr any
+--- @param buf integer|string
+--- @param expr string|function
 --- @return any
 function vim.fn.prompt_setinterrupt(buf, expr) end
 
@@ -6689,8 +6780,8 @@ function vim.fn.prompt_setinterrupt(buf, expr) end
 ---   call prompt_setprompt(bufnr(''), 'command: ')
 --- <
 ---
---- @param buf any
---- @param text any
+--- @param buf integer|string
+--- @param text string
 --- @return any
 function vim.fn.prompt_setprompt(buf, text) end
 
@@ -6766,7 +6857,7 @@ function vim.fn.pyxeval(expr) end
 ---   echo rand(seed) % 16  " random number 0 - 15
 --- <
 ---
---- @param expr? any
+--- @param expr? number
 --- @return any
 function vim.fn.rand(expr) end
 
@@ -6789,8 +6880,8 @@ function vim.fn.rand(expr) end
 --- <
 ---
 --- @param expr any
---- @param max? any
---- @param stride? any
+--- @param max? integer
+--- @param stride? integer
 --- @return any
 function vim.fn.range(expr, max, stride) end
 
@@ -6818,8 +6909,8 @@ function vim.fn.range(expr, max, stride) end
 --- Also see |readfile()| and |writefile()|.
 ---
 --- @param fname string
---- @param offset? any
---- @param size? any
+--- @param offset? integer
+--- @param size? integer
 --- @return any
 function vim.fn.readblob(fname, offset, size) end
 
@@ -6852,8 +6943,8 @@ function vim.fn.readblob(fname, offset, size) end
 --- <
 --- Returns an empty List on error.
 ---
---- @param directory any
---- @param expr? any
+--- @param directory string
+--- @param expr? integer
 --- @return any
 function vim.fn.readdir(directory, expr) end
 
@@ -6890,8 +6981,8 @@ function vim.fn.readdir(directory, expr) end
 --- Also see |writefile()|.
 ---
 --- @param fname string
---- @param type? any
---- @param max? any
+--- @param type? string
+--- @param max? integer
 --- @return any
 function vim.fn.readfile(fname, type, max) end
 
@@ -6913,7 +7004,7 @@ function vim.fn.readfile(fname, type, max) end
 --- <
 ---
 --- @param object any
---- @param func any
+--- @param func function
 --- @param initial? any
 --- @return any
 function vim.fn.reduce(object, func, initial) end
@@ -7019,9 +7110,9 @@ function vim.fn.remove(list, idx) end
 --- <
 --- Use |delete()| to remove a file.
 ---
---- @param list any
+--- @param list any[]
 --- @param idx integer
---- @param end_? any
+--- @param end_? integer
 --- @return any
 function vim.fn.remove(list, idx, end_) end
 
@@ -7044,7 +7135,7 @@ function vim.fn.remove(blob, idx) end
 ---
 --- @param blob any
 --- @param idx integer
---- @param end_? any
+--- @param end_? integer
 --- @return any
 function vim.fn.remove(blob, idx, end_) end
 
@@ -7055,7 +7146,7 @@ function vim.fn.remove(blob, idx, end_) end
 --- Returns zero on error.
 ---
 --- @param dict any
---- @param key any
+--- @param key string
 --- @return any
 function vim.fn.remove(dict, key) end
 
@@ -7066,8 +7157,8 @@ function vim.fn.remove(dict, key) end
 --- NOTE: If {to} exists it is overwritten without warning.
 --- This function is not available in the |sandbox|.
 ---
---- @param from any
---- @param to any
+--- @param from string
+--- @param to string
 --- @return any
 function vim.fn.rename(from, to) end
 
@@ -7081,7 +7172,7 @@ function vim.fn.rename(from, to) end
 --- <Results in ['a', 'b', 'a', 'b', 'a', 'b'].
 ---
 --- @param expr any
---- @param count any
+--- @param count integer
 --- @return any
 vim.fn['repeat'] = function(expr, count) end
 
@@ -7097,7 +7188,7 @@ vim.fn['repeat'] = function(expr, count) end
 --- current directory (provided the result is still a relative
 --- path name) and also keeps a trailing path separator.
 ---
---- @param filename any
+--- @param filename string
 --- @return any
 function vim.fn.resolve(filename) end
 
@@ -7128,7 +7219,7 @@ function vim.fn.reverse(object) end
 ---   echo round(-4.5)
 --- <  -5.0
 ---
---- @param expr any
+--- @param expr number
 --- @return any
 function vim.fn.round(expr) end
 
@@ -7138,8 +7229,8 @@ function vim.fn.round(expr) end
 ---   au VimLeave call rpcnotify(0, "leaving")
 --- <
 ---
---- @param channel any
---- @param event any
+--- @param channel integer
+--- @param event string
 --- @param args? any
 --- @return any
 function vim.fn.rpcnotify(channel, event, args) end
@@ -7150,19 +7241,20 @@ function vim.fn.rpcnotify(channel, event, args) end
 ---   let result = rpcrequest(rpc_chan, "func", 1, 2, 3)
 --- <
 ---
---- @param channel any
---- @param method any
+--- @param channel integer
+--- @param method string
 --- @param args? any
 --- @return any
 function vim.fn.rpcrequest(channel, method, args) end
 
+--- @deprecated
 --- Deprecated. Replace  >vim
 ---   let id = rpcstart('prog', ['arg1', 'arg2'])
 --- <with >vim
 ---   let id = jobstart(['prog', 'arg1', 'arg2'], {'rpc': v:true})
 --- <
 ---
---- @param prog any
+--- @param prog string
 --- @param argv? any
 --- @return any
 function vim.fn.rpcstart(prog, argv) end
@@ -7195,7 +7287,7 @@ function vim.fn.rubyeval(expr) end
 --- attribute at other positions.
 --- Returns -1 when row or col is out of range.
 ---
---- @param row any
+--- @param row integer
 --- @param col integer
 --- @return any
 function vim.fn.screenattr(row, col) end
@@ -7209,7 +7301,7 @@ function vim.fn.screenattr(row, col) end
 --- This is mainly to be used for testing.
 --- Returns -1 when row or col is out of range.
 ---
---- @param row any
+--- @param row integer
 --- @param col integer
 --- @return any
 function vim.fn.screenchar(row, col) end
@@ -7220,7 +7312,7 @@ function vim.fn.screenchar(row, col) end
 --- This is mainly to be used for testing.
 --- Returns an empty List when row or col is out of range.
 ---
---- @param row any
+--- @param row integer
 --- @param col integer
 --- @return any
 function vim.fn.screenchars(row, col) end
@@ -7236,7 +7328,7 @@ function vim.fn.screenchars(row, col) end
 --- the following mappings: >vim
 ---   nnoremap <expr> GG ":echom " .. screencol() .. "\n"
 ---   nnoremap <silent> GG :echom screencol()<CR>
----   noremap GG <Cmd>echom screencol()<Cr>
+---   noremap GG <Cmd>echom screencol()<CR>
 --- <
 ---
 --- @return any
@@ -7288,7 +7380,7 @@ function vim.fn.screenrow() end
 --- This is mainly to be used for testing.
 --- Returns an empty String when row or col is out of range.
 ---
---- @param row any
+--- @param row integer
 --- @param col integer
 --- @return any
 function vim.fn.screenstring(row, col) end
@@ -7347,6 +7439,9 @@ function vim.fn.screenstring(row, col) end
 --- The value must not be negative.  A zero value is like not
 --- giving the argument.
 ---
+--- Note: the timeout is only considered when searching, not
+--- while evaluating the {skip} expression.
+---
 --- If the {skip} expression is given it is evaluated with the
 --- cursor positioned on the start of a match.  If it evaluates to
 --- non-zero this match is skipped.  This can be used, for
@@ -7394,11 +7489,11 @@ function vim.fn.screenstring(row, col) end
 --- without the 'e' flag if the cursor is on the "f" of "if".
 --- The 'n' flag tells the function not to move the cursor.
 ---
---- @param pattern any
+--- @param pattern string
 --- @param flags? string
---- @param stopline? any
+--- @param stopline? integer
 --- @param timeout? integer
---- @param skip? any
+--- @param skip? string|function
 --- @return any
 function vim.fn.search(pattern, flags, stopline, timeout, skip) end
 
@@ -7545,8 +7640,8 @@ function vim.fn.searchcount(options) end
 --- <
 ---
 --- @param name string
---- @param global? any
---- @param thisblock? any
+--- @param global? boolean
+--- @param thisblock? boolean
 --- @return any
 function vim.fn.searchdecl(name, global, thisblock) end
 
@@ -7634,8 +7729,15 @@ function vim.fn.searchdecl(name, global, thisblock) end
 ---        \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
 --- <
 ---
---- @return any
-function vim.fn.searchpair() end
+--- @param start string
+--- @param middle string
+--- @param end_ string
+--- @param flags? string
+--- @param skip? string|function
+--- @param stopline? integer
+--- @param timeout? integer
+--- @return integer
+function vim.fn.searchpair(start, middle, end_, flags, skip, stopline, timeout) end
 
 --- Same as |searchpair()|, but returns a |List| with the line and
 --- column position of the match. The first element of the |List|
@@ -7647,8 +7749,15 @@ function vim.fn.searchpair() end
 --- <
 --- See |match-parens| for a bigger and more useful example.
 ---
---- @return any
-function vim.fn.searchpairpos() end
+--- @param start string
+--- @param middle string
+--- @param end_ string
+--- @param flags? string
+--- @param skip? string|function
+--- @param stopline? integer
+--- @param timeout? integer
+--- @return [integer, integer]
+function vim.fn.searchpairpos(start, middle, end_, flags, skip, stopline, timeout) end
 
 --- Same as |search()|, but returns a |List| with the line and
 --- column position of the match. The first element of the |List|
@@ -7664,11 +7773,11 @@ function vim.fn.searchpairpos() end
 --- <In this example "submatch" is 2 when a lowercase letter is
 --- found |/\l|, 3 when an uppercase letter is found |/\u|.
 ---
---- @param pattern any
+--- @param pattern string
 --- @param flags? string
---- @param stopline? any
+--- @param stopline? integer
 --- @param timeout? integer
---- @param skip? any
+--- @param skip? string|function
 --- @return any
 function vim.fn.searchpos(pattern, flags, stopline, timeout, skip) end
 
@@ -7714,7 +7823,7 @@ function vim.fn.serverlist() end
 ---   echo serverstart('::1:12345')
 --- <
 ---
---- @param address? any
+--- @param address? string
 --- @return any
 function vim.fn.serverstart(address) end
 
@@ -7723,7 +7832,7 @@ function vim.fn.serverstart(address) end
 --- If |v:servername| is stopped it is set to the next available
 --- address in |serverlist()|.
 ---
---- @param address any
+--- @param address string
 --- @return any
 function vim.fn.serverstop(address) end
 
@@ -7751,9 +7860,9 @@ function vim.fn.serverstop(address) end
 --- If {buf} is not a valid buffer or {lnum} is not valid, an
 --- error message is given.
 ---
---- @param buf any
+--- @param buf integer|string
 --- @param lnum integer
---- @param text any
+--- @param text string|string[]
 --- @return any
 function vim.fn.setbufline(buf, lnum, text) end
 
@@ -7770,7 +7879,7 @@ function vim.fn.setbufline(buf, lnum, text) end
 ---   call setbufvar("todo", "myvar", "foobar")
 --- <This function is not available in the |sandbox|.
 ---
---- @param buf any
+--- @param buf integer|string
 --- @param varname string
 --- @param val any
 --- @return any
@@ -7803,13 +7912,13 @@ function vim.fn.setbufvar(buf, varname, val) end
 --- To clear the overrides pass an empty {list}: >vim
 ---    call setcellwidths([])
 ---
---- <You can use the script $VIMRUNTIME/tools/emoji_list.vim to see
+--- <You can use the script $VIMRUNTIME/tools/emoji_list.lua to see
 --- the effect for known emoji characters.  Move the cursor
 --- through the text to check if the cell widths of your terminal
 --- match with what Vim knows about each emoji.  If it doesn't
 --- look right you need to adjust the {list} argument.
 ---
---- @param list any
+--- @param list any[]
 --- @return any
 function vim.fn.setcellwidths(list) end
 
@@ -7823,8 +7932,8 @@ function vim.fn.setcellwidths(list) end
 ---   call setpos('.', [0, 8, 4, 0])
 --- <positions the cursor on the second character '보'.
 ---
---- @param expr any
---- @param list any
+--- @param expr string
+--- @param list integer[]
 --- @return any
 function vim.fn.setcharpos(expr, list) end
 
@@ -7847,7 +7956,7 @@ function vim.fn.setcharpos(expr, list) end
 ---   call setcharsearch(prevsearch)
 --- <Also see |getcharsearch()|.
 ---
---- @param dict any
+--- @param dict string
 --- @return any
 function vim.fn.setcharsearch(dict) end
 
@@ -7857,8 +7966,8 @@ function vim.fn.setcharsearch(dict) end
 --- Returns 0 when successful, 1 when not editing the command
 --- line.
 ---
---- @param str any
---- @param pos? any
+--- @param str string
+--- @param pos? integer
 --- @return any
 function vim.fn.setcmdline(str, pos) end
 
@@ -7876,13 +7985,13 @@ function vim.fn.setcmdline(str, pos) end
 --- Returns 0 when successful, 1 when not editing the command
 --- line.
 ---
---- @param pos any
+--- @param pos integer
 --- @return any
 function vim.fn.setcmdpos(pos) end
 
 --- @param lnum integer
 --- @param col? integer
---- @param off? any
+--- @param off? integer
 --- @return any
 function vim.fn.setcursorcharpos(lnum, col, off) end
 
@@ -7896,7 +8005,7 @@ function vim.fn.setcursorcharpos(lnum, col, off) end
 ---   call cursor(4, 3)
 --- <positions the cursor on the first character '여'.
 ---
---- @param list any
+--- @param list integer[]
 --- @return any
 function vim.fn.setcursorcharpos(list) end
 
@@ -7907,7 +8016,7 @@ function vim.fn.setcursorcharpos(list) end
 --- See also |expr-env|.
 ---
 --- @param name string
---- @param val any
+--- @param val string
 --- @return any
 function vim.fn.setenv(name, val) end
 
@@ -7981,8 +8090,8 @@ function vim.fn.setline(lnum, text) end
 ---
 --- @param nr integer
 --- @param list any
---- @param action? any
---- @param what? any
+--- @param action? string
+--- @param what? table
 --- @return any
 function vim.fn.setloclist(nr, list, action, what) end
 
@@ -7994,7 +8103,7 @@ function vim.fn.setloclist(nr, list, action, what) end
 --- window ID instead of the current window.
 ---
 --- @param list any
---- @param win? any
+--- @param win? integer
 --- @return any
 function vim.fn.setmatches(list, win) end
 
@@ -8046,8 +8155,8 @@ function vim.fn.setmatches(list, win) end
 --- also set the preferred column.  Also see the "curswant" key in
 --- |winrestview()|.
 ---
---- @param expr any
---- @param list any
+--- @param expr string
+--- @param list integer[]
 --- @return any
 function vim.fn.setpos(expr, list) end
 
@@ -8164,9 +8273,9 @@ function vim.fn.setpos(expr, list) end
 --- independent of the 'errorformat' setting.  Use a command like
 --- `:cc 1` to jump to the first position.
 ---
---- @param list any
---- @param action? any
---- @param what? any
+--- @param list any[]
+--- @param action? string
+--- @param what? table
 --- @return any
 function vim.fn.setqflist(list, action, what) end
 
@@ -8301,7 +8410,7 @@ function vim.fn.settabwinvar(tabnr, winnr, varname, val) end
 ---
 --- @param nr integer
 --- @param dict any
---- @param action? any
+--- @param action? string
 --- @return any
 function vim.fn.settagstack(nr, dict, action) end
 
@@ -8355,7 +8464,7 @@ function vim.fn.sha256(string) end
 --- <See also |::S|.
 ---
 --- @param string string
---- @param special? any
+--- @param special? boolean
 --- @return any
 function vim.fn.shellescape(string, special) end
 
@@ -8400,6 +8509,7 @@ function vim.fn.sign_define(name, dict) end
 ---    icon    full path to the bitmap file for the sign.
 ---    linehl  highlight group used for the whole line the
 ---     sign is placed in.
+---    priority  default priority value of the sign
 ---    numhl  highlight group used for the line number where
 ---     the sign is placed.
 ---    text    text that is displayed when there is no icon
@@ -8450,6 +8560,7 @@ function vim.fn.sign_define(list) end
 ---    linehl  highlight group used for the whole line the
 ---     sign is placed in; not present if not set.
 ---    name    name of the sign
+---    priority  default priority value of the sign
 ---    numhl  highlight group used for the line number where
 ---     the sign is placed; not present if not set.
 ---    text    text that is displayed when there is no icon
@@ -8536,7 +8647,7 @@ function vim.fn.sign_getdefined(name) end
 ---   echo sign_getplaced()
 --- <
 ---
---- @param buf? any
+--- @param buf? integer|string
 --- @param dict? vim.fn.sign_getplaced.dict
 --- @return vim.fn.sign_getplaced.ret.item[]
 function vim.fn.sign_getplaced(buf, dict) end
@@ -8610,10 +8721,10 @@ function vim.fn.sign_jump(id, group, buf) end
 ---       \ {'lnum' : 40, 'priority' : 90})
 --- <
 ---
---- @param id any
---- @param group any
+--- @param id integer
+--- @param group string
 --- @param name string
---- @param buf any
+--- @param buf integer|string
 --- @param dict? vim.fn.sign_place.dict
 --- @return integer
 function vim.fn.sign_place(id, group, name, buf, dict) end
@@ -8641,7 +8752,8 @@ function vim.fn.sign_place(id, group, name, buf, dict) end
 ---     priority  Priority of the sign. When multiple signs are
 ---     placed on a line, the sign with the highest
 ---     priority is used. If not specified, the
----     default value of 10 is used. See
+---     default value of 10 is used, unless specified
+---     otherwise by the sign definition. See
 ---     |sign-priority| for more information.
 ---
 --- If {id} refers to an existing sign, then the existing sign is
@@ -8804,7 +8916,7 @@ function vim.fn.sign_unplacelist(list) end
 --- directory.  In order to resolve all the involved symbolic
 --- links before simplifying the path name, use |resolve()|.
 ---
---- @param filename any
+--- @param filename string
 --- @return any
 function vim.fn.simplify(filename) end
 
@@ -8817,7 +8929,7 @@ function vim.fn.simplify(filename) end
 ---   echo sin(-4.01)
 --- <  0.763301
 ---
---- @param expr any
+--- @param expr number
 --- @return any
 function vim.fn.sin(expr) end
 
@@ -8831,7 +8943,7 @@ function vim.fn.sin(expr) end
 ---   echo sinh(-0.9)
 --- <  -1.026517
 ---
---- @param expr any
+--- @param expr number
 --- @return any
 function vim.fn.sinh(expr) end
 
@@ -8845,8 +8957,8 @@ function vim.fn.sinh(expr) end
 --- Returns an empty value if {start} or {end} are invalid.
 ---
 --- @param expr any
---- @param start any
---- @param end_? any
+--- @param start integer
+--- @param end_? integer
 --- @return any
 function vim.fn.slice(expr, start, end_) end
 
@@ -8875,7 +8987,7 @@ function vim.fn.slice(expr, start, end_) end
 ---   - 0 on invalid arguments or connection failure.
 ---
 --- @param mode string
---- @param address any
+--- @param address string
 --- @param opts? table
 --- @return any
 function vim.fn.sockconnect(mode, address, opts) end
@@ -8953,7 +9065,7 @@ function vim.fn.sockconnect(mode, address, opts) end
 --- <
 ---
 --- @param list any
---- @param how? any
+--- @param how? string|function
 --- @param dict? any
 --- @return any
 function vim.fn.sort(list, how, dict) end
@@ -8965,7 +9077,7 @@ function vim.fn.sort(list, how, dict) end
 --- This can be used for making spelling suggestions.  Note that
 --- the method can be quite slow.
 ---
---- @param word any
+--- @param word string
 --- @return any
 function vim.fn.soundfold(word) end
 
@@ -8992,7 +9104,7 @@ function vim.fn.soundfold(word) end
 --- The spelling information for the current window and the value
 --- of 'spelllang' are used.
 ---
---- @param sentence? any
+--- @param sentence? string
 --- @return any
 function vim.fn.spellbadword(sentence) end
 
@@ -9016,15 +9128,15 @@ function vim.fn.spellbadword(sentence) end
 --- The spelling information for the current window is used.  The
 --- values of 'spelllang' and 'spellsuggest' are used.
 ---
---- @param word any
---- @param max? any
---- @param capital? any
+--- @param word string
+--- @param max? integer
+--- @param capital? boolean
 --- @return any
 function vim.fn.spellsuggest(word, max, capital) end
 
 --- Make a |List| out of {string}.  When {pattern} is omitted or
---- empty each white-separated sequence of characters becomes an
---- item.
+--- empty each white space separated sequence of characters
+--- becomes an item.
 --- Otherwise the string is split where {pattern} matches,
 --- removing the matched characters. 'ignorecase' is not used
 --- here, add \c to ignore case. |/\c|
@@ -9047,8 +9159,8 @@ function vim.fn.spellsuggest(word, max, capital) end
 --- <The opposite function is |join()|.
 ---
 --- @param string string
---- @param pattern? any
---- @param keepempty? any
+--- @param pattern? string
+--- @param keepempty? boolean
 --- @return any
 function vim.fn.split(string, pattern, keepempty) end
 
@@ -9064,7 +9176,7 @@ function vim.fn.split(string, pattern, keepempty) end
 --- <  str2float("nan")
 --- NaN may be different, it depends on system libraries.
 ---
---- @param expr any
+--- @param expr number
 --- @return any
 function vim.fn.sqrt(expr) end
 
@@ -9082,7 +9194,7 @@ function vim.fn.sqrt(expr) end
 ---   echo rand(seed)
 --- <
 ---
---- @param expr? any
+--- @param expr? number
 --- @return any
 function vim.fn.srand(expr) end
 
@@ -9187,7 +9299,7 @@ function vim.fn.stdpath(what) end
 --- Returns 0.0 if the conversion fails.
 ---
 --- @param string string
---- @param quoted? any
+--- @param quoted? boolean
 --- @return any
 function vim.fn.str2float(string, quoted) end
 
@@ -9203,7 +9315,7 @@ function vim.fn.str2float(string, quoted) end
 ---   echo str2list("á")    " returns [97, 769]
 ---
 --- @param string string
---- @param utf8? any
+--- @param utf8? boolean
 --- @return any
 function vim.fn.str2list(string, utf8) end
 
@@ -9226,7 +9338,7 @@ function vim.fn.str2list(string, utf8) end
 --- Returns 0 if {string} is empty or on error.
 ---
 --- @param string string
---- @param base? any
+--- @param base? integer
 --- @return any
 function vim.fn.str2nr(string, base) end
 
@@ -9257,10 +9369,10 @@ function vim.fn.strcharlen(string) end
 ---
 --- Returns an empty string on error.
 ---
---- @param src any
---- @param start any
---- @param len? any
---- @param skipcc? any
+--- @param src string
+--- @param start integer
+--- @param len? integer
+--- @param skipcc? boolean
 --- @return any
 function vim.fn.strcharpart(src, start, len, skipcc) end
 
@@ -9293,7 +9405,7 @@ function vim.fn.strcharpart(src, start, len, skipcc) end
 --- <
 ---
 --- @param string string
---- @param skipcc? any
+--- @param skipcc? boolean
 --- @return integer
 function vim.fn.strchars(string, skipcc) end
 
@@ -9331,8 +9443,8 @@ function vim.fn.strdisplaywidth(string, col) end
 ---   echo strftime("%c", getftime("file.c"))
 ---            " Show mod time of file.c.
 ---
---- @param format any
---- @param time? any
+--- @param format string
+--- @param time? number
 --- @return string
 function vim.fn.strftime(format, time) end
 
@@ -9796,7 +9908,7 @@ function vim.fn.synIDtrans(synID) end
 ---
 --- @param lnum integer
 --- @param col integer
---- @return {[1]: integer, [2]: string, [3]: integer}
+--- @return [integer, string, integer]
 function vim.fn.synconcealed(lnum, col) end
 
 --- Return a |List|, which is the stack of syntax items at the
@@ -9906,7 +10018,7 @@ function vim.fn.systemlist(cmd, input, keepempty) end
 ---   endfor
 --- <Note that a buffer may appear in more than one window.
 ---
---- @param arg? any
+--- @param arg? integer
 --- @return any
 function vim.fn.tabpagebuflist(arg) end
 
@@ -10049,7 +10161,7 @@ function vim.fn.tempname() end
 --- except $TERM is set to "xterm-256color". Full behavior is
 --- described in |terminal|.
 ---
---- @param cmd any
+--- @param cmd string|string[]
 --- @param opts? table
 --- @return any
 function vim.fn.termopen(cmd, opts) end
@@ -10068,7 +10180,7 @@ function vim.fn.termopen(cmd, opts) end
 ---         -1 means forever
 ---     "callback"      the callback
 ---
---- @param id? any
+--- @param id? integer
 --- @return any
 function vim.fn.timer_info(id) end
 
@@ -10084,8 +10196,8 @@ function vim.fn.timer_info(id) end
 --- String, then the timer is paused, otherwise it is unpaused.
 --- See |non-zero-arg|.
 ---
---- @param timer any
---- @param paused any
+--- @param timer integer
+--- @param paused boolean
 --- @return any
 function vim.fn.timer_pause(timer, paused) end
 
@@ -10118,8 +10230,8 @@ function vim.fn.timer_pause(timer, paused) end
 ---     \ {'repeat': 3})
 --- <This invokes MyHandler() three times at 500 msec intervals.
 ---
---- @param time any
---- @param callback any
+--- @param time number
+--- @param callback string|function
 --- @param options? table
 --- @return any
 function vim.fn.timer_start(time, callback, options) end
@@ -10128,7 +10240,7 @@ function vim.fn.timer_start(time, callback, options) end
 --- {timer} is an ID returned by timer_start(), thus it must be a
 --- Number.  If {timer} does not exist there is no error.
 ---
---- @param timer any
+--- @param timer integer
 --- @return any
 function vim.fn.timer_stop(timer) end
 
@@ -10143,7 +10255,7 @@ function vim.fn.timer_stopall() end
 --- characters turned into lowercase (just like applying |gu| to
 --- the string).  Returns an empty string on error.
 ---
---- @param expr any
+--- @param expr string
 --- @return string
 function vim.fn.tolower(expr) end
 
@@ -10151,7 +10263,7 @@ function vim.fn.tolower(expr) end
 --- characters turned into uppercase (just like applying |gU| to
 --- the string).  Returns an empty string on error.
 ---
---- @param expr any
+--- @param expr string
 --- @return string
 function vim.fn.toupper(expr) end
 
@@ -10203,7 +10315,7 @@ function vim.fn.tr(src, fromstr, tostr) end
 ---   echo trim("  vim  ", " ", 2)
 --- <returns "  vim"
 ---
---- @param text any
+--- @param text string
 --- @param mask? string
 --- @param dir? 0|1|2
 --- @return string
@@ -10221,7 +10333,7 @@ function vim.fn.trim(text, mask, dir) end
 ---   echo trunc(4.0)
 --- <  4.0
 ---
---- @param expr any
+--- @param expr number
 --- @return integer
 function vim.fn.trunc(expr) end
 
@@ -10250,6 +10362,7 @@ function vim.fn.trunc(expr) end
 ---   if myvar is v:null | endif
 --- <To check if the v:t_ variables exist use this: >vim
 ---   if exists('v:t_number') | endif
+--- <
 ---
 --- @param expr any
 --- @return integer
@@ -10313,7 +10426,7 @@ function vim.fn.undofile(name) end
 ---     item.
 ---
 --- @param buf? integer|string
---- @return any
+--- @return vim.fn.undotree.ret
 function vim.fn.undotree(buf) end
 
 --- Remove second and succeeding copies of repeated adjacent
@@ -10360,8 +10473,8 @@ function vim.fn.uniq(list, func, dict) end
 ---
 --- @param string string
 --- @param idx integer
---- @param countcc? any
---- @param charidx? any
+--- @param countcc? boolean
+--- @param charidx? boolean
 --- @return integer
 function vim.fn.utf16idx(string, idx, countcc, charidx) end
 
@@ -10382,7 +10495,9 @@ function vim.fn.values(dict) end
 --- set to 8, it returns 8. |conceal| is ignored.
 --- For the byte position use |col()|.
 ---
---- For the use of {expr} see |col()|.
+--- For the use of {expr} see |getpos()| and |col()|.
+--- When {expr} is "$", it means the end of the cursor line, so
+--- the result is the number of cells in the cursor line plus one.
 ---
 --- When 'virtualedit' is used {expr} can be [lnum, col, off],
 --- where "off" is the offset in screen columns from the start of
@@ -10392,18 +10507,6 @@ function vim.fn.values(dict) end
 --- beyond the end of the line can be returned.  Also see
 --- |'virtualedit'|
 ---
---- The accepted positions are:
----     .      the cursor position
----     $      the end of the cursor line (the result is the
----       number of displayed characters in the cursor line
----       plus one)
----     'x      position of mark x (if the mark is not set, 0 is
----       returned)
----     v       In Visual mode: the start of the Visual area (the
----       cursor is the end).  When not in Visual mode
----       returns the cursor position.  Differs from |'<| in
----       that it's updated right away.
----
 --- If {list} is present and non-zero then virtcol() returns a
 --- List with the first and last screen position occupied by the
 --- character.
@@ -10422,13 +10525,16 @@ function vim.fn.values(dict) end
 ---   " With text "    there", with 't at 'h':
 ---
 ---   echo virtcol("'t")  " returns 6
---- <The first column is 1.  0 or [0, 0] is returned for an error.
+--- <
+--- The first column is 1.  0 or [0, 0] is returned for an error.
+---
 --- A more advanced example that echoes the maximum length of
 --- all lines: >vim
 ---     echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
+--- <
 ---
---- @param expr any
---- @param list? any
+--- @param expr string|integer[]
+--- @param list? boolean
 --- @param winid? integer
 --- @return any
 function vim.fn.virtcol(expr, list, winid) end
@@ -10477,7 +10583,7 @@ function vim.fn.virtcol2col(winid, lnum, col) end
 --- a non-empty String, then the Visual mode will be cleared and
 --- the old value is returned.  See |non-zero-arg|.
 ---
---- @param expr? any
+--- @param expr? boolean
 --- @return any
 function vim.fn.visualmode(expr) end
 
@@ -10498,7 +10604,7 @@ function vim.fn.visualmode(expr) end
 ---
 --- @param timeout integer
 --- @param condition any
---- @param interval? any
+--- @param interval? number
 --- @return any
 function vim.fn.wait(timeout, condition, interval) end
 
@@ -10528,8 +10634,8 @@ function vim.fn.wildmenumode() end
 --- When window {id} does not exist then no error is given and
 --- an empty string is returned.
 ---
---- @param id any
---- @param command any
+--- @param id integer
+--- @param command string
 --- @param silent? boolean
 --- @return any
 function vim.fn.win_execute(id, command, silent) end
@@ -10537,7 +10643,7 @@ function vim.fn.win_execute(id, command, silent) end
 --- Returns a |List| with |window-ID|s for windows that contain
 --- buffer {bufnr}.  When there is none the list is empty.
 ---
---- @param bufnr any
+--- @param bufnr integer
 --- @return integer[]
 function vim.fn.win_findbuf(bufnr) end
 
@@ -10549,8 +10655,8 @@ function vim.fn.win_findbuf(bufnr) end
 --- number {tab}.  The first tab has number one.
 --- Return zero if the window cannot be found.
 ---
---- @param win? any
---- @param tab? any
+--- @param win? integer
+--- @param tab? integer
 --- @return integer
 function vim.fn.win_getid(win, tab) end
 
@@ -10579,7 +10685,7 @@ function vim.fn.win_gettype(nr) end
 --- tabpage.
 --- Return TRUE if successful, FALSE if the window cannot be found.
 ---
---- @param expr any
+--- @param expr integer
 --- @return 0|1
 function vim.fn.win_gotoid(expr) end
 
@@ -10587,14 +10693,14 @@ function vim.fn.win_gotoid(expr) end
 --- with ID {expr}: [tabnr, winnr].
 --- Return [0, 0] if the window cannot be found.
 ---
---- @param expr any
+--- @param expr integer
 --- @return any
 function vim.fn.win_id2tabwin(expr) end
 
 --- Return the window number of window with ID {expr}.
 --- Return 0 if the window cannot be found in the current tabpage.
 ---
---- @param expr any
+--- @param expr integer
 --- @return any
 function vim.fn.win_id2win(expr) end
 
@@ -10613,7 +10719,7 @@ function vim.fn.win_id2win(expr) end
 --- Only works for the current tab page. *E1308*
 ---
 --- @param nr integer
---- @param offset any
+--- @param offset integer
 --- @return any
 function vim.fn.win_move_separator(nr, offset) end
 
@@ -10629,7 +10735,7 @@ function vim.fn.win_move_separator(nr, offset) end
 --- Only works for the current tab page.
 ---
 --- @param nr integer
---- @param offset any
+--- @param offset integer
 --- @return any
 function vim.fn.win_move_statusline(nr, offset) end
 
@@ -10664,7 +10770,7 @@ function vim.fn.win_screenpos(nr) end
 ---     'splitright' are used.
 ---
 --- @param nr integer
---- @param target any
+--- @param target integer
 --- @param options? table
 --- @return any
 function vim.fn.win_splitmove(nr, target, options) end
@@ -10706,6 +10812,7 @@ function vim.fn.windowsversion() end
 --- This excludes any window toolbar line.
 --- Examples: >vim
 ---   echo "The current window has " .. winheight(0) .. " lines."
+--- <
 ---
 --- @param nr integer
 --- @return integer
@@ -10789,8 +10896,9 @@ function vim.fn.winline() end
 ---   let window_count = winnr('$')
 ---   let prev_window = winnr('#')
 ---   let wnum = winnr('3k')
+--- <
 ---
---- @param arg? any
+--- @param arg? string|integer
 --- @return any
 function vim.fn.winnr(arg) end
 
@@ -10939,6 +11047,7 @@ function vim.fn.wordcount() end
 --- To copy a file byte for byte: >vim
 ---   let fl = readfile("foo", "b")
 ---   call writefile(fl, "foocopy", "b")
+--- <
 ---
 --- @param object any
 --- @param fname string
@@ -10953,7 +11062,7 @@ function vim.fn.writefile(object, fname, flags) end
 ---   let bits = xor(bits, 0x80)
 --- <
 ---
---- @param expr any
---- @param expr1 any
+--- @param expr number
+--- @param expr1 number
 --- @return any
 function vim.fn.xor(expr, expr1) end