From 9c718bc2bce53b5be45061bff940f99e50c8bfcb Mon Sep 17 00:00:00 2001
From: luukvbaal <luukvbaal@gmail.com>
Date: Sun, 17 Nov 2024 00:36:11 +0100
Subject: 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.
---
 runtime/doc/api.txt | 31 +++++++++++++++----------------
 1 file changed, 15 insertions(+), 16 deletions(-)

(limited to 'runtime/doc')

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 50c35a0fc6..c5dabeb551 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -658,8 +658,8 @@ nvim_echo({chunks}, {history}, {opts})                           *nvim_echo()*
 
     Parameters: ~
       • {chunks}   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.
       • {history}  if true, add to |message-history|.
       • {opts}     Optional parameters.
                    • verbose: Message is printed as a result of 'verbose'
@@ -2672,8 +2672,10 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts})
                   • 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 cursorline highlight).
@@ -2682,9 +2684,7 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts})
                     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()|.
+                    last).
                   • virt_text_pos : position of virtual text. Possible values:
                     • "eol": right after eol character (default).
                     • "overlay": display over the specified column, without
@@ -2750,15 +2750,14 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts})
                     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|.
-- 
cgit