neovim

commit 4f3f81ed86542109824bd199198fb43e6fccdc17
parent 668f16bac779ac52d7bd9452e6001a7a6d1e9965
Author: JP <17429390+resolritter@users.noreply.github.com>
Date:   Sun, 30 Apr 2023 06:02:38 -0300

docs(api): document nvim_buf_add_highlight vs nvim_buf_set_extmark (#23310)


Diffstat:
M
runtime/doc/api.txt
 | 
17
+++++++++++++++++

1 file changed, 17 insertions(+), 0 deletions(-)
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
@@ -400,6 +400,23 @@ external highlighter plugin wants to add many highlights in a batch,
 performance can be improved by calling |nvim_buf_add_highlight()| as an
 asynchronous notification, after first (synchronously) requesting a source id.
 
+|nvim_buf_add_highlight()| adds highlights as |extmarks|. If highlights need to
+be tracked or manipulated after adding them, it is better to use
+|nvim_buf_set_extmark()| directly, as this function returns the placed |extmark|
+id. Thus, instead of >lua
+  vim.api.nvim_buf_add_highlight(buf, ns_id, hl_group, line, col_start, col_end)
+<
+use >lua
+  -- create the highlight through an extmark
+  extid = vim.api.nvim_buf_set_extmark(buf, ns_id, hl_group, line, col_start, {end_col = col_end, hl_group = hl_group})
+
+  -- example: modify the extmark's highlight group
+  vim.api.nvim_buf_set_extmark(buf, ns_id, NEW_HL_GROUP, line, col_start, {end_col = col_end, hl_group = hl_group, id = extid})
+
+  -- example: change the highlight's position
+  vim.api.nvim_buf_set_extmark(buf, ns_id, hl_group, NEW_LINE, col_start, {end_col = col_end, hl_group = hl_group, id = extid})
+<
+
 Example using the Python API client (|pynvim|):
 >python
     src = vim.new_highlight_source()