refactor(api): nvim_win_xx_ns are EXPERIMENTAL

Problem:
The nvim_win_xx_ns function family introduced in ba0370b1d7
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:/…)"

runtime/doc/api.txt

@@ -2777,7 +2777,7 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts})
                     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: ~
         Id of the created/updated extmark
@@ -2859,7 +2859,9 @@ nvim_set_decoration_provider({ns_id}, {opts})
                     ["end", tick]
 <
 
-nvim_win_add_ns({window}, {ns_id})                         *nvim_win_add_ns()*
+nvim__win_add_ns({window}, {ns_id})                       *nvim__win_add_ns()*
+    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.
 
@@ -2870,7 +2872,9 @@ nvim_win_add_ns({window}, {ns_id})                         *nvim_win_add_ns()*
     Return: ~
         true if the namespace was added, else false
 
-nvim_win_del_ns({window}, {ns_id})                         *nvim_win_del_ns()*
+nvim__win_del_ns({window}, {ns_id})                       *nvim__win_del_ns()*
+    EXPERIMENTAL: this API will change in the future.
+
     Unscopes a namespace (un-binds it from the given scope).
 
     Parameters: ~
@@ -2880,7 +2884,9 @@ nvim_win_del_ns({window}, {ns_id})                         *nvim_win_del_ns()*
     Return: ~
         true if the namespace was removed, else false
 
-nvim_win_get_ns({window})                                  *nvim_win_get_ns()*
+nvim__win_get_ns({window})                                *nvim__win_get_ns()*
+    EXPERIMENTAL: this API will change in the future.
+
     Gets the namespace scopes for a given window.
 
     Parameters: ~

runtime/doc/news.txt

@@ -216,7 +216,7 @@ The following new APIs and features were added.
     |nvim_win_set_config()|.
   • |nvim_input_mouse()| supports mouse buttons "x1" and "x2".
   • Added |nvim_tabpage_set_win()| to set the current window of a tabpage.
-  • |nvim_win_add_ns()| can bind a |namespace| to a window-local scope(s).
+  • |nvim__win_add_ns()| can bind a |namespace| to a window-local scope(s).
     • Extmarks opt-in to this scoping via the `scoped` flag of |nvim_buf_set_extmark()|.
 
 • 'foldtext' now supports virtual text format. |fold-foldtext|

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

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)

src/nvim/api/extmark.c

@@ -490,7 +490,7 @@ Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id, Object start, Object e
 ///               - url: A URL to associate with this extmark. In the TUI, the 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()|
+///                 |nvim__win_add_ns()|
 ///
 /// @param[out]  err   Error details, if any
 /// @return Id of the created/updated extmark
@@ -1215,14 +1215,15 @@ String nvim__buf_debug_extmarks(Buffer buffer, Boolean keys, Boolean dot, Error
   return mt_inspect(buf->b_marktree, keys, dot);
 }
 
+/// 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 Window handle, or 0 for current window
 /// @param ns_id Namespace
 /// @return true if the namespace was added, else false
-Boolean nvim_win_add_ns(Window window, Integer ns_id, Error *err)
+Boolean nvim__win_add_ns(Window window, Integer ns_id, Error *err)
-  FUNC_API_SINCE(12)
 {
   win_T *win = find_window_by_handle(window, err);
   if (!win) {
@@ -1242,12 +1243,13 @@ Boolean nvim_win_add_ns(Window window, Integer ns_id, Error *err)
   return true;
 }
 
+/// EXPERIMENTAL: this API will change in the future.
+///
 /// Gets the namespace scopes for a given window.
 ///
 /// @param window Window handle, or 0 for current window
 /// @return a list of namespaces ids
-ArrayOf(Integer) nvim_win_get_ns(Window window, Arena *arena, Error *err)
+ArrayOf(Integer) nvim__win_get_ns(Window window, Arena *arena, Error *err)
-  FUNC_API_SINCE(12)
 {
   win_T *win = find_window_by_handle(window, err);
   if (!win) {
@@ -1263,13 +1265,14 @@ ArrayOf(Integer) nvim_win_get_ns(Window window, Arena *arena, Error *err)
   return rv;
 }
 
+/// EXPERIMENTAL: this API will change in the future.
+///
 /// Unscopes a namespace (un-binds it from the given scope).
 ///
 /// @param window Window handle, or 0 for current window
 /// @param ns_id the namespace to remove
 /// @return true if the namespace was removed, else false
-Boolean nvim_win_del_ns(Window window, Integer ns_id, Error *err)
+Boolean nvim__win_del_ns(Window window, Integer ns_id, Error *err)
-  FUNC_API_SINCE(12)
 {
   win_T *win = find_window_by_handle(window, err);
   if (!win) {

test/functional/lua/highlight_spec.lua

@@ -43,9 +43,9 @@ describe('vim.highlight.on_yank', function()
       vim.api.nvim_buf_set_mark(0,"]",1,1,{})
       vim.highlight.on_yank({timeout = math.huge, on_macro = true, event = {operator = "y"}})
     ]])
-    neq({}, api.nvim_win_get_ns(0))
+    neq({}, api.nvim__win_get_ns(0))
     command('wincmd w')
-    eq({}, api.nvim_win_get_ns(0))
+    eq({}, api.nvim__win_get_ns(0))
   end)
 
   it('removes old highlight if new one is created before old one times out', function()
@@ -55,7 +55,7 @@ describe('vim.highlight.on_yank', function()
       vim.api.nvim_buf_set_mark(0,"]",1,1,{})
       vim.highlight.on_yank({timeout = math.huge, on_macro = true, event = {operator = "y"}})
     ]])
-    neq({}, api.nvim_win_get_ns(0))
+    neq({}, api.nvim__win_get_ns(0))
     command('wincmd w')
     exec_lua([[
       vim.api.nvim_buf_set_mark(0,"[",1,1,{})
@@ -63,6 +63,6 @@ describe('vim.highlight.on_yank', function()
       vim.highlight.on_yank({timeout = math.huge, on_macro = true, event = {operator = "y"}})
     ]])
     command('wincmd w')
-    eq({}, api.nvim_win_get_ns(0))
+    eq({}, api.nvim__win_get_ns(0))
   end)
 end)

test/functional/ui/decorations_spec.lua

@@ -5610,7 +5610,7 @@ describe('decorations: window scoped', function()
 
     screen:expect(noextmarks)
 
-    api.nvim_win_add_ns(0, ns)
+    api.nvim__win_add_ns(0, ns)
 
     screen:expect {
       grid = [[
@@ -5645,7 +5645,7 @@ describe('decorations: window scoped', function()
 
     screen:expect(noextmarks)
 
-    api.nvim_win_add_ns(0, ns)
+    api.nvim__win_add_ns(0, ns)
 
     screen:expect {
       grid = [[
@@ -5667,7 +5667,7 @@ describe('decorations: window scoped', function()
 
     screen:expect(noextmarks)
 
-    api.nvim_win_add_ns(0, ns)
+    api.nvim__win_add_ns(0, ns)
 
     screen:expect {
       grid = [[
@@ -5691,7 +5691,7 @@ describe('decorations: window scoped', function()
 
     screen:expect(noextmarks)
 
-    api.nvim_win_add_ns(0, ns)
+    api.nvim__win_add_ns(0, ns)
 
     screen:expect {
       grid = [[
@@ -5701,7 +5701,7 @@ describe('decorations: window scoped', function()
                           |
     ]]}
 
-    api.nvim_win_del_ns(0, ns)
+    api.nvim__win_del_ns(0, ns)
 
     screen:expect(noextmarks)
   end)
@@ -5716,7 +5716,7 @@ describe('decorations: window scoped', function()
 
     screen:expect(noextmarks)
 
-    api.nvim_win_add_ns(0, ns)
+    api.nvim__win_add_ns(0, ns)
 
     screen:expect {
       grid = [[
@@ -5748,7 +5748,7 @@ describe('decorations: window scoped', function()
                           |
     ]]}
 
-    api.nvim_win_add_ns(0, ns)
+    api.nvim__win_add_ns(0, ns)
 
     screen:expect {
       grid = [[
@@ -5787,7 +5787,7 @@ describe('decorations: window scoped', function()
                           |
     ]]}
 
-    api.nvim_win_add_ns(0, ns)
+    api.nvim__win_add_ns(0, ns)
 
     screen:expect {
       grid = [[
@@ -5815,7 +5815,7 @@ describe('decorations: window scoped', function()
 
     screen:expect(noextmarks)
 
-    api.nvim_win_add_ns(0, ns)
+    api.nvim__win_add_ns(0, ns)
 
     screen:expect {
       grid = [[
@@ -5836,7 +5836,7 @@ describe('decorations: window scoped', function()
       end_col = 3,
     })
 
-    api.nvim_win_add_ns(0, ns)
+    api.nvim__win_add_ns(0, ns)
 
     screen:expect {
       grid = [[
@@ -5880,8 +5880,8 @@ describe('decorations: window scoped', function()
       end_col = 3,
     })
 
-    eq(true, api.nvim_win_add_ns(0, ns))
+    eq(true, api.nvim__win_add_ns(0, ns))
-    eq({ ns }, api.nvim_win_get_ns(0))
+    eq({ ns }, api.nvim__win_get_ns(0))
 
     screen:expect {
       grid = [[
@@ -5892,12 +5892,12 @@ describe('decorations: window scoped', function()
 
     command 'split'
     command 'only'
-    eq({}, api.nvim_win_get_ns(0))
+    eq({}, api.nvim__win_get_ns(0))
 
     screen:expect(noextmarks)
 
-    eq(true, api.nvim_win_add_ns(0, ns))
+    eq(true, api.nvim__win_add_ns(0, ns))
-    eq({ ns }, api.nvim_win_get_ns(0))
+    eq({ ns }, api.nvim__win_get_ns(0))
 
     screen:expect {
       grid = [[
@@ -5906,8 +5906,8 @@ describe('decorations: window scoped', function()
                           |
     ]]}
 
-    eq(true, api.nvim_win_del_ns(0, ns))
+    eq(true, api.nvim__win_del_ns(0, ns))
-    eq({}, api.nvim_win_get_ns(0))
+    eq({}, api.nvim__win_get_ns(0))
 
     screen:expect(noextmarks)
   end)