feat(docs): replace lua2dox.lua

Problem:

The documentation flow (`gen_vimdoc.py`) has several issues:
- it's not very versatile
- depends on doxygen
- doesn't work well with Lua code as it requires an awkward filter script to convert it into pseudo-C.
- The intermediate XML files and filters makes it too much like a rube goldberg machine.

Solution:

Re-implement the flow using Lua, LPEG and treesitter.

- `gen_vimdoc.py` is now replaced with `gen_vimdoc.lua` and replicates a portion of the logic.
- `lua2dox.lua` is gone!
- No more XML files.
- Doxygen is now longer used and instead we now use:
  - LPEG for comment parsing (see `scripts/luacats_grammar.lua` and `scripts/cdoc_grammar.lua`).
  - LPEG for C parsing (see `scripts/cdoc_parser.lua`)
  - Lua patterns for Lua parsing (see `scripts/luacats_parser.lua`).
  - Treesitter for Markdown parsing (see `scripts/text_utils.lua`).
- The generated `runtime/doc/*.mpack` files have been removed.
   - `scripts/gen_eval_files.lua` now instead uses `scripts/cdoc_parser.lua` directly.
- Text wrapping is implemented in `scripts/text_utils.lua` and appears to produce more consistent results (the main contributer to the diff of this change).

35 files changed, 1009 insertions, 911 deletions

diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index c5a6e65e86..4e39abb2be 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -127,10 +127,10 @@ vim.log = {
 ---     timeout the process is sent the KILL signal (9) and the exit code is set to 124. Cannot
 ---     be called in |api-fast|.
 ---     - SystemCompleted is an object with the fields:
----      - code: (integer)
----      - signal: (integer)
----      - stdout: (string), nil if stdout argument is passed
----      - stderr: (string), nil if stderr argument is passed
+---       - code: (integer)
+---       - signal: (integer)
+---       - stdout: (string), nil if stdout argument is passed
+---       - stderr: (string), nil if stderr argument is passed
 ---   - kill (fun(signal: integer|string))
 ---   - write (fun(data: string|nil)) Requires `stdin=true`. Pass `nil` to close the stream.
 ---   - is_closing (fun(): boolean)
@@ -706,8 +706,8 @@ end
 --- Generates a list of possible completions for the string.
 --- String has the pattern.
 ---
----     1. Can we get it to just return things in the global namespace with that name prefix
----     2. Can we get it to return things from global namespace even with `print(` in front.
+--- 1. Can we get it to just return things in the global namespace with that name prefix
+--- 2. Can we get it to return things from global namespace even with `print(` in front.
 ---
 --- @param pat string
 function vim._expand_pat(pat, env)
@@ -885,6 +885,7 @@ do
   --- similar to the builtin completion for the `:lua` command.
   ---
   --- Activate using `set omnifunc=v:lua.vim.lua_omnifunc` in a Lua buffer.
+  --- @param find_start 1|0
   function vim.lua_omnifunc(find_start, _)
     if find_start == 1 then
       local line = vim.api.nvim_get_current_line()
@@ -914,6 +915,7 @@ end
 ---
 --- @see |vim.inspect()|
 --- @see |:=|
+--- @param ... any
 --- @return any # given arguments.
 function vim.print(...)
   if vim.in_fast_event() then
diff --git a/runtime/lua/vim/_inspector.lua b/runtime/lua/vim/_inspector.lua
index 3f7b9d2c23..9a073c32c4 100644
--- a/runtime/lua/vim/_inspector.lua
+++ b/runtime/lua/vim/_inspector.lua
@@ -17,7 +17,7 @@ local defaults = {
 ---@param bufnr? integer defaults to the current buffer
 ---@param row? integer row to inspect, 0-based. Defaults to the row of the current cursor
 ---@param col? integer col to inspect, 0-based. Defaults to the col of the current cursor
----@param filter? InspectorFilter (table|nil) a table with key-value pairs to filter the items
+---@param filter? InspectorFilter (table) a table with key-value pairs to filter the items
 ---               - syntax (boolean): include syntax based highlight groups (defaults to true)
 ---               - treesitter (boolean): include treesitter based highlight groups (defaults to true)
 ---               - extmarks (boolean|"all"): include extmarks. When `all`, then extmarks without a `hl_group` will also be included (defaults to true)
@@ -139,7 +139,7 @@ end
 ---@param bufnr? integer defaults to the current buffer
 ---@param row? integer row to inspect, 0-based. Defaults to the row of the current cursor
 ---@param col? integer col to inspect, 0-based. Defaults to the col of the current cursor
----@param filter? InspectorFilter (table|nil) see |vim.inspect_pos()|
+---@param filter? InspectorFilter (table) see |vim.inspect_pos()|
 function vim.show_pos(bufnr, row, col, filter)
   local items = vim.inspect_pos(bufnr, row, col, filter)
 
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index aee866f324..d2f624fd97 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.
 ---
@@ -108,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
@@ -131,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):
 ---
@@ -148,6 +156,7 @@ 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
@@ -155,77 +164,70 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start
 ---                    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.
+---             • 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
 
@@ -238,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`.
@@ -279,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.
 ---
@@ -296,8 +300,8 @@ 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
@@ -319,14 +323,15 @@ 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
+---             • 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` 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:
@@ -338,12 +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
@@ -361,23 +369,23 @@ 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"
+---             • 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
 
@@ -389,9 +397,11 @@ function vim.api.nvim_buf_get_extmarks(buffer, ns_id, start, end_, opts) end
 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.
 ---
@@ -405,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
@@ -424,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.
 ---
@@ -443,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
@@ -485,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
@@ -502,114 +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.
----               • 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