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

1 files changed, 611 insertions, 410 deletions

diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index 49269ba631..cb4c8749b8 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -38,6 +38,7 @@ function vim.api.nvim__get_runtime(pat, all, opts) end
 
 --- @private
 --- Returns object given as argument.
+---
 --- This API function is used for testing. One should not rely on its presence
 --- in plugins.
 ---
@@ -47,6 +48,7 @@ function vim.api.nvim__id(obj) end
 
 --- @private
 --- Returns array given as argument.
+---
 --- This API function is used for testing. One should not rely on its presence
 --- in plugins.
 ---
@@ -56,6 +58,7 @@ function vim.api.nvim__id_array(arr) end
 
 --- @private
 --- Returns dictionary given as argument.
+---
 --- This API function is used for testing. One should not rely on its presence
 --- in plugins.
 ---
@@ -65,6 +68,7 @@ function vim.api.nvim__id_dictionary(dct) end
 
 --- @private
 --- Returns floating-point value given as argument.
+---
 --- This API function is used for testing. One should not rely on its presence
 --- in plugins.
 ---
@@ -73,6 +77,9 @@ function vim.api.nvim__id_dictionary(dct) end
 function vim.api.nvim__id_float(flt) end
 
 --- @private
+--- NB: if your UI doesn't use hlstate, this will not return hlstate first
+--- time.
+---
 --- @param grid integer
 --- @param row integer
 --- @param col integer
@@ -105,17 +112,20 @@ function vim.api.nvim__stats() end
 function vim.api.nvim__unpack(str) 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.
+---
 --- 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`.
+---
 --- 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
 --- string no highlight is added, but a new `ns_id` is still returned. This is
@@ -128,11 +138,12 @@ function vim.api.nvim__unpack(str) end
 --- @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
+---                highlight to end of line
 --- @return integer
 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):
 ---
@@ -145,76 +156,78 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start
 ---     })
 --- ```
 ---
+---
 --- @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.
---- @param opts table<string,function> Optional parameters.
----                    • on_lines: Lua callback invoked on change. Return `true` 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 `true` 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
----                      • old end column of the changed text
----                      • old end byte length of the changed text
----                      • new end row of the changed text
----                      • new end column of the changed text
----                      • 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.
+--- @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
 function vim.api.nvim_buf_attach(buffer, send_buffer, opts) end
 
 --- 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 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)
+---            only)
 --- @return any
 function vim.api.nvim_buf_call(buffer, fun) end
 
@@ -227,14 +240,15 @@ function vim.api.nvim_buf_clear_highlight(buffer, ns_id, line_start, line_end) e
 
 --- Clears `namespace`d objects (highlights, `extmarks`, virtual text) from a
 --- region.
+---
 --- 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.
+--- @param line_end integer End of range of lines to clear (exclusive) or -1 to clear
+---                 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`.
@@ -268,6 +282,7 @@ function vim.api.nvim_buf_del_keymap(buffer, mode, lhs) end
 function vim.api.nvim_buf_del_mark(buffer, name) end
 
 --- Delete a buffer-local user-defined command.
+---
 --- Only commands created with `:command-buffer` or
 --- `nvim_buf_create_user_command()` can be deleted with this function.
 ---
@@ -284,9 +299,9 @@ function vim.api.nvim_buf_del_var(buffer, name) end
 --- Deletes the buffer. See `:bwipeout`
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
---- @param opts table<string,any> Optional parameters. Keys:
----               • force: Force deletion and ignore unsaved changes.
----               • unload: Unloaded only, do not delete. See `:bunload`
+--- @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`
 function vim.api.nvim_buf_delete(buffer, opts) end
 
 --- Gets a changed tick of a buffer
@@ -307,15 +322,16 @@ function vim.api.nvim_buf_get_commands(buffer, 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
---- @param opts table<string,any> 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 integer[]
+--- @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
 function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end
 
---- Gets `extmarks` (including `signs`) in "traversal order" from a `charwise`
---- region defined by buffer positions (inclusive, 0-indexed `api-indexing`).
+--- Gets `extmarks` in "traversal order" from a `charwise` region defined by
+--- buffer positions (inclusive, 0-indexed `api-indexing`).
+---
 --- Region can be given as (row,col) tuples, or valid extmark ids (whose
 --- positions define the bounds). 0 and -1 are understood as (0,0) and (-1,-1)
 --- respectively, thus the following are equivalent:
@@ -327,9 +343,15 @@ function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end
 ---
 --- 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.
+---
+--- 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
@@ -347,37 +369,39 @@ function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end
 ---     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
+---              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 any[]
+---             • 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[]
 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 table<string,any>[]
+--- @return vim.api.keyset.keymap[]
 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.
+---
 --- Out-of-bounds indices are clamped to the nearest valid value, unless
 --- `strict_indexing` is set.
 ---
@@ -391,6 +415,7 @@ 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`.
+---
 --- Marks are (1,0)-indexed. `api-indexing`
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
@@ -410,10 +435,12 @@ function vim.api.nvim_buf_get_name(buffer) end
 function vim.api.nvim_buf_get_number(buffer) end
 
 --- Returns the byte offset of a line (0-indexed). `api-indexing`
+---
 --- Line 1 (index=0) has offset 0. UTF-8 bytes are counted. EOL is one byte.
 --- 'fileformat' and 'fileencoding' are ignored. The line index just after the
 --- 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.
 ---
@@ -429,10 +456,13 @@ function vim.api.nvim_buf_get_offset(buffer, index) end
 function vim.api.nvim_buf_get_option(buffer, name) end
 
 --- Gets a range from the buffer.
+---
 --- This differs from `nvim_buf_get_lines()` in that it allows retrieving only
 --- portions of a line.
+---
 --- Indexing is zero-based. Row indices are end-inclusive, and column indices
 --- are end-exclusive.
+---
 --- Prefer `nvim_buf_get_lines()` when retrieving entire lines.
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
@@ -440,7 +470,7 @@ function vim.api.nvim_buf_get_option(buffer, name) end
 --- @param start_col integer Starting column (byte offset) on first line
 --- @param end_row integer Last line index, inclusive
 --- @param end_col integer Ending column (byte offset) on last line, exclusive
---- @param opts table<string,any> Optional parameters. Currently unused.
+--- @param opts vim.api.keyset.empty Optional parameters. Currently unused.
 --- @return string[]
 function vim.api.nvim_buf_get_text(buffer, start_row, start_col, end_row, end_col, opts) end
 
@@ -471,13 +501,16 @@ function vim.api.nvim_buf_is_valid(buffer) end
 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.)
+---
 --- 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
@@ -488,108 +521,110 @@ 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.
----               • 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. If
----                 "undo_restore" is false, the extmark is deleted instead.
----               • priority: a priority value for the highlight group or sign
----                 attribute. 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. Note: ranges are unsupported and decorations
----                 are only applied to start_row
----               • sign_hl_group: name of the highlight group used to
----                 highlight the sign column text. Note: ranges are
----                 unsupported and decorations are only applied to start_row
----               • number_hl_group: name of the highlight group used to
----                 highlight the number column. Note: ranges are unsupported
----                 and decorations are only applied to start_row
----               • line_hl_group: name of the highlight group used to
----                 highlight the whole line. Note: ranges are unsupported and
----                 decorations are only applied to start_row
----               • cursorline_hl_group: name of the highlight group used to
----                 highlight the line when the cursor is on the same line as
----                 the mark and 'cursorline' is enabled. Note: ranges are
----                 unsupported and decorations are only applied to start_row
----               • 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.
+---             • 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 that indicates that the extmark should only
+---               be displayed in the namespace scope. (experimental)
 --- @return integer
 function vim.api.nvim_buf_set_extmark(buffer, ns_id, line, col, opts) end
 
@@ -603,11 +638,14 @@ function vim.api.nvim_buf_set_extmark(buffer, ns_id, line, col, opts) end
 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.
+---
 --- 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.
+---
 --- Out-of-bounds indices are clamped to the nearest valid value, unless
 --- `strict_indexing` is set.
 ---
@@ -620,13 +658,14 @@ function vim.api.nvim_buf_set_lines(buffer, start, end_, strict_indexing, replac
 
 --- Sets a named mark in the given buffer, all marks are allowed
 --- file/uppercase, visual, last change, etc. See `mark-motions`.
+---
 --- Marks are (1,0)-indexed. `api-indexing`
 ---
 --- @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 table<string,any> Optional parameters. Reserved for future use.
+--- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use.
 --- @return boolean
 function vim.api.nvim_buf_set_mark(buffer, name, line, col, opts) end
 
@@ -643,16 +682,21 @@ function vim.api.nvim_buf_set_name(buffer, name) end
 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.
+---
 --- 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.
+---
 --- Prefer `nvim_put()` if you want to insert text at the cursor position.
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
@@ -675,11 +719,12 @@ function vim.api.nvim_buf_set_var(buffer, name, value) end
 --- @param src_id integer
 --- @param line integer
 --- @param chunks any[]
---- @param opts table<string,any>
+--- @param opts vim.api.keyset.empty
 --- @return integer
 function vim.api.nvim_buf_set_virtual_text(buffer, src_id, line, chunks, opts) end
 
 --- Calls a Vimscript `Dictionary-function` with the given arguments.
+---
 --- On execution error: fails with Vimscript error, updates v:errmsg.
 ---
 --- @param dict any Dictionary, or String evaluating to a Vimscript `self` dict
@@ -689,6 +734,7 @@ function vim.api.nvim_buf_set_virtual_text(buffer, src_id, line, chunks, opts) e
 function vim.api.nvim_call_dict_function(dict, fn, args) end
 
 --- Calls a Vimscript function with the given arguments.
+---
 --- On execution error: fails with Vimscript error, updates v:errmsg.
 ---
 --- @param fn string Function to call
@@ -700,6 +746,7 @@ function vim.api.nvim_call_function(fn, args) end
 --- 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.
@@ -716,41 +763,41 @@ function vim.api.nvim_chan_send(chan, data) end
 ---               • 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.
+---               • 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.
+---
 --- 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()`.