docs: details dict in nvim_buf_get_extmark() #35289

Problem: The document of nvim_buf_get_extmark currently lacks the
following:
- "details" directory: nvim_buf_get_extmarks() allows an option details
  to get a "details" directory in result, but it doesn't mention where
  that "details" directory is, what fields does it have.

Solution: Add docs for "details" directory in nvim_buf_get_extmarks()

runtime/doc/api.txt

@@ -3041,7 +3041,14 @@ nvim_buf_get_extmark_by_id({buffer}, {ns_id}, {id}, {opts})
 
     Return: ~
         (`[integer, integer, vim.api.keyset.extmark_details?]`) 0-indexed
-        (row, col) tuple or empty list () if extmark id was absent
+        (row, col, details?) tuple or empty list () if extmark id was absent.
+        The optional `details` dictionary contains the same keys as `opts` in
+        |nvim_buf_set_extmark()|, except for `id`, `conceal_lines` and
+        `ephemeral`. It also contains the following keys:
+        • ns_id: |namespace| id
+        • invalid: boolean that indicates whether the mark is hidden because
+          the entirety of text span range is deleted. See also the key
+          `invalidate` in |nvim_buf_set_extmark()|.
 
                                                      *nvim_buf_get_extmarks()*
 nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts})
@@ -3108,8 +3115,9 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts})
                     "virt_text" and "virt_lines"
 
     Return: ~
-        (`vim.api.keyset.get_extmark_item[]`) List of `[extmark_id, row, col]`
+        (`vim.api.keyset.get_extmark_item[]`) List of
-        tuples in "traversal order".
+        `[extmark_id, row, col, details?]` tuples in "traversal order". For
+        the `details` dictionary, see |nvim_buf_get_extmark_by_id()|.
 
                                                       *nvim_buf_set_extmark()*
 nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts})

runtime/lua/vim/_meta/api.lua

@@ -359,8 +359,13 @@ function vim.api.nvim_buf_get_commands(buffer, opts) end
 --- @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 [integer, integer, vim.api.keyset.extmark_details?] # 0-indexed (row, col) tuple or empty list () if extmark id was
+--- @return [integer, integer, vim.api.keyset.extmark_details?] # 0-indexed (row, col, details?) tuple or empty list () if extmark id was absent.  The
---- absent
+--- optional `details` dictionary contains the same keys as `opts` in |nvim_buf_set_extmark()|,
+--- except for `id`, `conceal_lines` and `ephemeral`. It also contains the following keys:
+---
+--- - ns_id: |namespace| id
+--- - invalid: boolean that indicates whether the mark is hidden because the entirety of
+--- text span range is deleted. See also the key `invalidate` in |nvim_buf_set_extmark()|.
 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
@@ -419,7 +424,8 @@ function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end
 --- - 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".
+--- @return vim.api.keyset.get_extmark_item[] # List of `[extmark_id, row, col, details?]` tuples in "traversal order". For the
+--- `details` dictionary, see |nvim_buf_get_extmark_by_id()|.
 function vim.api.nvim_buf_get_extmarks(buffer, ns_id, start, end_, opts) end
 
 --- Gets a list of buffer-local `mapping` definitions.

src/nvim/api/extmark.c

@@ -197,8 +197,13 @@ static Array extmark_to_array(MTPair extmark, bool id, bool add_dict, bool hl_na
 ///          - details: Whether to include the details dict
 ///          - hl_name: Whether to include highlight group name instead of id, true if omitted
 /// @param[out] err   Error details, if any
-/// @return 0-indexed (row, col) tuple or empty list () if extmark id was
+/// @return 0-indexed (row, col, details?) tuple or empty list () if extmark id was absent.  The
-/// absent
+/// optional `details` dictionary contains the same keys as `opts` in |nvim_buf_set_extmark()|,
+/// except for `id`, `conceal_lines` and `ephemeral`. It also contains the following keys:
+///
+/// - ns_id: |namespace| id
+/// - invalid: boolean that indicates whether the mark is hidden because the entirety of
+/// text span range is deleted. See also the key `invalidate` in |nvim_buf_set_extmark()|.
 Tuple(Integer, Integer, *DictAs(extmark_details))
 nvim_buf_get_extmark_by_id(Buffer buffer, Integer ns_id, Integer id, Dict(get_extmark) * opts,
                            Arena *arena, Error *err)
@@ -284,7 +289,8 @@ nvim_buf_get_extmark_by_id(Buffer buffer, Integer ns_id, Integer id, Dict(get_ex
 ///                     their start position is less than `start`
 ///          - type: Filter marks by type: "highlight", "sign", "virt_text" and "virt_lines"
 /// @param[out] err   Error details, if any
-/// @return List of `[extmark_id, row, col]` tuples in "traversal order".
+/// @return List of `[extmark_id, row, col, details?]` tuples in "traversal order". For the
+/// `details` dictionary, see |nvim_buf_get_extmark_by_id()|.
 ArrayOf(DictAs(get_extmark_item)) nvim_buf_get_extmarks(Buffer buffer, Integer ns_id, Object start,
                                                         Object end,
                                                         Dict(get_extmarks) *opts, Arena *arena,