fix(api): validation, documentation of hl_group #31195

Problem:  Documentation for "hl_group" in nvim_buf_set_extmark() is
          unclear. "hl_group" in nvim_echo() does not accept
          highlight group id.
Solution: Move documentation for highlight group name/id to first
          mention of hl_group. Update nvim_echo() to accept highlight
          group id.

1 files changed, 12 insertions, 16 deletions

diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index 30654efdea..3c9b9d4f44 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -592,8 +592,9 @@ function vim.api.nvim_buf_line_count(buffer) end
 --- - 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_group : highlight group used for the text range. This and below
+---     highlight groups can be supplied either as a string or as an integer,
+---     the latter of which can be obtained using `nvim_get_hl_id_by_name()`.
 --- - 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
@@ -603,9 +604,7 @@ function vim.api.nvim_buf_line_count(buffer) end
 ---     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()`.
+---     (highest priority last).
 --- - virt_text_pos : position of virtual text. Possible values:
 ---   - "eol": right after eol character (default).
 ---   - "overlay": display over the specified column, without
@@ -676,15 +675,12 @@ function vim.api.nvim_buf_line_count(buffer) end
 ---     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.
+--- - sign_hl_group: highlight group used for the sign column text.
+--- - number_hl_group: highlight group used for the number column.
+--- - line_hl_group: highlight group used for the whole line.
+--- - cursorline_hl_group: highlight group used for 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`.
@@ -1106,8 +1102,8 @@ function vim.api.nvim_del_var(name) end
 --- Echo a message.
 ---
 --- @param chunks any[] A list of `[text, hl_group]` arrays, each representing a
---- text chunk with specified highlight. `hl_group` element
---- can be omitted for no highlight.
+--- text chunk with specified highlight group name or ID.
+--- `hl_group` element can be omitted for no highlight.
 --- @param history boolean if true, add to `message-history`.
 --- @param opts vim.api.keyset.echo_opts Optional parameters.
 --- - verbose: Message is printed as a result of 'verbose' option.