feat(api): deprecate nvim_buf_add_highlight()

This was kept for a while as it was a useful short hand and initially
matched what highlights what actually properly implemented. But now
|vim.hl.range()| is a better high-level shorthand with full support for
native multi-line ranges.
This commit is contained in:
bfredl
2025-01-19 13:30:11 +01:00
parent 71507281fb
commit 19b25f3fea
7 changed files with 110 additions and 202 deletions

View File

@@ -163,35 +163,14 @@ function vim.api.nvim__stats() end
--- @return any
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
--- supported for backwards compatibility, new code should use
--- `nvim_create_namespace()` to create a new empty namespace.
---
--- @param buffer integer Buffer handle, or 0 for current buffer
--- @param ns_id integer namespace to use or -1 for ungrouped highlight
--- @param hl_group string Name of the highlight group to use
--- @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
--- @return integer # The ns_id that was used
--- @deprecated
--- @param buffer integer
--- @param ns_id integer
--- @param hl_group string
--- @param line integer
--- @param col_start integer
--- @param col_end integer
--- @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.
@@ -987,7 +966,7 @@ function vim.api.nvim_create_buf(listed, scratch) end
--- Creates a new namespace or gets an existing one. [namespace]()
---
--- Namespaces are used for buffer highlights and virtual text, see
--- `nvim_buf_add_highlight()` and `nvim_buf_set_extmark()`.
--- `nvim_buf_set_extmark()`.
---
--- Namespaces can be named or anonymous. If `name` matches an existing
--- namespace, the associated id is returned. If `name` is an empty string