commit 798bb3f66ae9a400d0215285771343e2bffd01a7
parent da39966a3a0a6165caa3d7ce913316a98ebe9308
Author: Phạm Bình An <111893501+brianhuster@users.noreply.github.com>
Date: Sun, 7 Sep 2025 03:38:31 +0700
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()
Diffstat:
3 files changed, 29 insertions(+), 9 deletions(-)
diff --git a/runtime/doc/api.txt b/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]`
- tuples in "traversal order".
+ (`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()|.
*nvim_buf_set_extmark()*
nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts})
diff --git a/runtime/lua/vim/_meta/api.lua b/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
---- absent
+--- @return [integer, integer, vim.api.keyset.extmark_details?] # 0-indexed (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()|.
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.
diff --git a/src/nvim/api/extmark.c b/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
-/// absent
+/// @return 0-indexed (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()|.
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,
