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

2 files changed, 8 insertions, 5 deletions

diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 315ccd13e6..a8cc7aa454 100644
--- a/src/nvim/api/vim.c
+++ b/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
diff --git a/src/nvim/api/window.c b/src/nvim/api/window.c
index e2c234ab29..abe11e6b72 100644
--- a/src/nvim/api/window.c
+++ b/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.
 ///