docs(api): link to nvim_set_hl_ns from nvim_set_hl (#22678)

1 files changed, 10 insertions, 5 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index d16b9274dc..b8590026c8 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -1399,6 +1399,9 @@ nvim_set_hl({ns_id}, {name}, {*val})                           *nvim_set_hl()*
     Parameters: ~
       • {ns_id}  Namespace id for this highlight |nvim_create_namespace()|.
                  Use 0 to set a highlight group globally |:highlight|.
+                 Highlights from non-global namespaces are not active by
+                 default, use |nvim_set_hl_ns()| or |nvim_win_set_hl_ns()| to
+                 activate them.
       • {name}   Highlight group name, e.g. "ErrorMsg"
       • {val}    Highlight definition map, accepts the following keys:
                  • fg (or foreground): color name or "#RRGGBB", see note.
@@ -1426,14 +1429,15 @@ nvim_set_hl({ns_id}, {name}, {*val})                           *nvim_set_hl()*
                    map documented above.
 
 nvim_set_hl_ns({ns_id})                                     *nvim_set_hl_ns()*
-    Set active namespace for highlights. This can be set for a single window,
-    see |nvim_win_set_hl_ns()|.
+    Set active namespace for highlights defined with |nvim_set_hl()|. This can
+    be set for a single window, see |nvim_win_set_hl_ns()|.
 
     Parameters: ~
       • {ns_id}  the namespace to use
 
 nvim_set_hl_ns_fast({ns_id})                           *nvim_set_hl_ns_fast()*
-    Set active namespace for highlights while redrawing.
+    Set active namespace for highlights defined with |nvim_set_hl()| while
+    redrawing.
 
     This function meant to be called while redrawing, primarily from
     |nvim_set_decoration_provider()| on_win and on_line callbacks, which are
@@ -2921,8 +2925,9 @@ nvim_win_set_height({window}, {height})                *nvim_win_set_height()*
       • {height}  Height as a count of rows
 
 nvim_win_set_hl_ns({window}, {ns_id})                   *nvim_win_set_hl_ns()*
-    Set highlight namespace for a window. This will use highlights defined in
-    this namespace, but fall back to global highlights (ns=0) when missing.
+    Set highlight namespace for a window. This will use highlights defined
+    with |nvim_set_hl()| for this namespace, but fall back to global
+    highlights (ns=0) when missing.
 
     This takes precedence over the 'winhighlight' option.