refactor(api): nvim_win_xx_ns are EXPERIMENTAL

Problem:
The nvim_win_xx_ns function family introduced in ba0370b1d718d473d0ef51c35d88b98ba220082b
needs more bake-time. Currently it's narrowly defined for windows, but
other scopes ("buffer") and features are likely in the future.

Solution:
- Rename the API with double-underscore to mark it as EXPERIMENTAL.

TODO/FUTURE:
- Rename and change the signature to support more than just "window"
  scope, and for other flexibility.
- Open question: we could choose either:
  - "store scopes on namespaces", or
  - "store namespaces on scopes (w:/b:/…)"

2 files changed, 33 insertions, 24 deletions

diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index dbd3c61634..6edf2a5a96 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -144,6 +144,36 @@ function vim.api.nvim__stats() end
 --- @return any
 function vim.api.nvim__unpack(str) end
 
+--- @private
+--- EXPERIMENTAL: this API will change in the future.
+---
+--- Scopes a namespace to the a window, so extmarks in the namespace will be
+--- active only in the given window.
+---
+--- @param window integer Window handle, or 0 for current window
+--- @param ns_id integer Namespace
+--- @return boolean
+function vim.api.nvim__win_add_ns(window, ns_id) end
+
+--- @private
+--- EXPERIMENTAL: this API will change in the future.
+---
+--- Unscopes a namespace (un-binds it from the given scope).
+---
+--- @param window integer Window handle, or 0 for current window
+--- @param ns_id integer the namespace to remove
+--- @return boolean
+function vim.api.nvim__win_del_ns(window, ns_id) end
+
+--- @private
+--- EXPERIMENTAL: this API will change in the future.
+---
+--- Gets the namespace scopes for a given window.
+---
+--- @param window integer Window handle, or 0 for current window
+--- @return integer[]
+function vim.api.nvim__win_get_ns(window) end
+
 --- Adds a highlight to buffer.
 ---
 --- Useful for plugins that dynamically generate highlights to a buffer (like
@@ -657,7 +687,7 @@ function vim.api.nvim_buf_line_count(buffer) end
 ---               OSC 8 control sequence is used to generate a clickable
 ---               hyperlink to this URL.
 ---             • scoped: boolean (EXPERIMENTAL) enables "scoping" for the
----               extmark. See `nvim_win_add_ns()`
+---               extmark. See `nvim__win_add_ns()`
 --- @return integer
 function vim.api.nvim_buf_set_extmark(buffer, ns_id, line, col, opts) end
 
@@ -2114,14 +2144,6 @@ function vim.api.nvim_tabpage_set_var(tabpage, name, value) end
 --- @param win integer Window handle, must already belong to {tabpage}
 function vim.api.nvim_tabpage_set_win(tabpage, win) end
 
---- Scopes a namespace to the a window, so extmarks in the namespace will be
---- active only in the given window.
----
---- @param window integer Window handle, or 0 for current window
---- @param ns_id integer Namespace
---- @return boolean
-function vim.api.nvim_win_add_ns(window, ns_id) end
-
 --- Calls a function with window as temporary current window.
 ---
 --- @param window integer Window handle, or 0 for current window
@@ -2138,13 +2160,6 @@ function vim.api.nvim_win_call(window, fun) end
 ---              hidden, even if 'hidden' is not set.
 function vim.api.nvim_win_close(window, force) end
 
---- Unscopes a namespace (un-binds it from the given scope).
----
---- @param window integer Window handle, or 0 for current window
---- @param ns_id integer the namespace to remove
---- @return boolean
-function vim.api.nvim_win_del_ns(window, ns_id) end
-
 --- Removes a window-scoped (w:) variable
 ---
 --- @param window integer Window handle, or 0 for current window
@@ -2181,12 +2196,6 @@ function vim.api.nvim_win_get_cursor(window) end
 --- @return integer
 function vim.api.nvim_win_get_height(window) end
 
---- Gets the namespace scopes for a given window.
----
---- @param window integer Window handle, or 0 for current window
---- @return integer[]
-function vim.api.nvim_win_get_ns(window) end
-
 --- Gets the window number
 ---
 --- @param window integer Window handle, or 0 for current window
diff --git a/runtime/lua/vim/highlight.lua b/runtime/lua/vim/highlight.lua
index da3d7fd361..f278bd357f 100644
--- a/runtime/lua/vim/highlight.lua
+++ b/runtime/lua/vim/highlight.lua
@@ -129,7 +129,7 @@ function M.on_yank(opts)
     yank_cancel()
   end
 
-  vim.api.nvim_win_add_ns(winid, yank_ns)
+  vim.api.nvim__win_add_ns(winid, yank_ns)
   M.range(bufnr, yank_ns, higroup, "'[", "']", {
     regtype = event.regtype,
     inclusive = event.inclusive,
@@ -141,7 +141,7 @@ function M.on_yank(opts)
     yank_timer = nil
     yank_cancel = nil
     pcall(vim.api.nvim_buf_clear_namespace, bufnr, yank_ns, 0, -1)
-    pcall(vim.api.nvim_win_del_ns, winid, yank_ns)
+    pcall(vim.api.nvim__win_del_ns, winid, yank_ns)
   end
 
   yank_timer = vim.defer_fn(yank_cancel, timeout)