docs(api): nvim_set_hl attributes #18558

2 files changed, 67 insertions, 17 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index b5ec9114de..812208ca31 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -1570,18 +1570,46 @@ nvim_set_current_win({window})                        *nvim_set_current_win()*
 nvim_set_hl({ns_id}, {name}, {*val})                           *nvim_set_hl()*
                 Sets a highlight group.
 
-                Note: Unlike the `:highlight` command which can update a
-                highlight group, this function completely replaces the
-                definition. For example: `nvim_set_hl(0, 'Visual', {})` will
-                clear the highlight group 'Visual'.
+                Note:
+                    Unlike the `:highlight` command which can update a
+                    highlight group, this function completely replaces the
+                    definition. For example: `nvim_set_hl(0, 'Visual', {})`
+                    will clear the highlight group 'Visual'.
+
+                Note:
+                    The fg and bg keys also accept the string values `"fg"` or
+                    `"bg"` which act as aliases to the corresponding
+                    foreground and background values of the Normal group. If
+                    the Normal group has not been defined, using these values
+                    results in an error.
 
                 Parameters: ~
                     {ns_id}  Namespace id for this highlight
                              |nvim_create_namespace()|. Use 0 to set a
                              highlight group globally |:highlight|.
                     {name}   Highlight group name, e.g. "ErrorMsg"
-                    {val}    Highlight definition map, like |synIDattr()|. In
-                             addition, the following keys are recognized:
+                    {val}    Highlight definition map, accepts the following
+                             keys:
+                             • fg (or foreground): color name or "#RRGGBB",
+                               see note.
+                             • bg (or background): color name or "#RRGGBB",
+                               see note.
+                             • sp (or special): color name or "#RRGGBB"
+                             • blend: integer between 0 and 100
+                             • bold: boolean
+                             • standout: boolean
+                             • underline: boolean
+                             • underlineline: boolean
+                             • undercurl: boolean
+                             • underdot: boolean
+                             • underdash: boolean
+                             • strikethrough: boolean
+                             • italic: boolean
+                             • reverse: boolean
+                             • nocombine: boolean
+                             • link: name of another highlight group to link
+                               to, see |:hi-link|. Additionally, the following
+                               keys are recognized:
                              • default: Don't override existing definition
                                |:hi-default|
                              • ctermfg: Sets foreground of cterm color
@@ -1589,8 +1617,9 @@ nvim_set_hl({ns_id}, {name}, {*val})                           *nvim_set_hl()*
                              • ctermbg: Sets background of cterm color
                                |highlight-ctermbg|
                              • cterm: cterm attribute map, like
-                               |highlight-args|. Note: Attributes default to
-                               those set for `gui` if not set.
+                               |highlight-args|. If not set, cterm attributes
+                               will match those from the attribute map
+                               documented above.
 
 nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts})             *nvim_set_keymap()*
                 Sets a global |mapping| for the given mode.
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index fca86fe440..a257dd6478 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -126,22 +126,43 @@ Dictionary nvim__get_hl_defs(Integer ns_id, Error *err)
 
 /// Sets a highlight group.
 ///
-/// Note: Unlike the `:highlight` command which can update a highlight group,
-/// this function completely replaces the definition. For example:
-/// ``nvim_set_hl(0, 'Visual', {})`` will clear the highlight group 'Visual'.
+/// @note Unlike the `:highlight` command which can update a highlight group,
+///       this function completely replaces the definition. For example:
+///       ``nvim_set_hl(0, 'Visual', {})`` will clear the highlight group
+///       'Visual'.
+///
+/// @note The fg and bg keys also accept the string values `"fg"` or `"bg"`
+///       which act as aliases to the corresponding foreground and background
+///       values of the Normal group. If the Normal group has not been defined,
+///       using these values results in an error.
 ///
 /// @param ns_id Namespace id for this highlight |nvim_create_namespace()|.
 ///              Use 0 to set a highlight group globally |:highlight|.
 /// @param name  Highlight group name, e.g. "ErrorMsg"
-/// @param val   Highlight definition map, like |synIDattr()|. In
-///              addition, the following keys are recognized:
+/// @param val   Highlight definition map, accepts the following keys:
+///                - fg (or foreground): color name or "#RRGGBB", see note.
+///                - bg (or background): color name or "#RRGGBB", see note.
+///                - sp (or special): color name or "#RRGGBB"
+///                - blend: integer between 0 and 100
+///                - bold: boolean
+///                - standout: boolean
+///                - underline: boolean
+///                - underlineline: boolean
+///                - undercurl: boolean
+///                - underdot: boolean
+///                - underdash: boolean
+///                - strikethrough: boolean
+///                - italic: boolean
+///                - reverse: boolean
+///                - nocombine: boolean
+///                - link: name of another highlight group to link to, see |:hi-link|.
+///              Additionally, the following keys are recognized:
 ///                - default: Don't override existing definition |:hi-default|
 ///                - ctermfg: Sets foreground of cterm color |highlight-ctermfg|
 ///                - ctermbg: Sets background of cterm color |highlight-ctermbg|
-///                - cterm: cterm attribute map, like
-///                  |highlight-args|.
-///                  Note: Attributes default to those set for `gui`
-///                        if not set.
+///                - cterm: cterm attribute map, like |highlight-args|. If not set,
+///                         cterm attributes will match those from the attribute map
+///                         documented above.
 /// @param[out] err Error details, if any
 ///
 // TODO(bfredl): val should take update vs reset flag