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

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.
 

src/nvim/api/vim.c

@@ -141,6 +141,8 @@ Dictionary nvim__get_hl_defs(Integer ns_id, Arena *arena, Error *err)
 ///
 /// @param 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.
 /// @param name  Highlight group name, e.g. "ErrorMsg"
 /// @param val   Highlight definition map, accepts the following keys:
 ///                - fg (or foreground): color name or "#RRGGBB", see note.
@@ -183,8 +185,8 @@ void nvim_set_hl(Integer ns_id, String name, Dict(highlight) *val, Error *err)
   }
 }
 
-/// 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()|.
 ///
 /// @param ns_id the namespace to use
 /// @param[out] err Error details, if any
@@ -200,7 +202,7 @@ void nvim_set_hl_ns(Integer ns_id, Error *err)
   redraw_all_later(UPD_NOT_VALID);
 }
 
-/// 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

src/nvim/api/window.c

@@ -445,8 +445,9 @@ Object nvim_win_call(Window window, LuaRef fun, Error *err)
   return res;
 }
 
-/// 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.
 ///