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 "overl