refactor(api): rename nvim_win_remove_ns

Problem:
nvim_win_remove_ns does not follow `help dev-naming` API naming conventions.

Solution:
Rename it.

runtime/doc/api.txt

@@ -2776,8 +2776,8 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts})
                   • 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 that indicates that the extmark should
+                  • scoped: boolean (EXPERIMENTAL) enables "scoping" for the
-                    only be displayed in the namespace scope. (experimental)
+                    extmark. See |nvim_win_add_ns()|
 
     Return: ~
         Id of the created/updated extmark
@@ -2860,26 +2860,18 @@ nvim_set_decoration_provider({ns_id}, {opts})
 <
 
 nvim_win_add_ns({window}, {ns_id})                         *nvim_win_add_ns()*
-    Adds the namespace scope to the window.
+    Scopes a namespace to the a window, so extmarks in the namespace will be
+    active only in the given window.
 
     Parameters: ~
       • {window}  Window handle, or 0 for current window
-      • {ns_id}   the namespace to add
+      • {ns_id}   Namespace
 
     Return: ~
         true if the namespace was added, else false
 
-nvim_win_get_ns({window})                                  *nvim_win_get_ns()*
+nvim_win_del_ns({window}, {ns_id})                         *nvim_win_del_ns()*
-    Gets all the namespaces scopes associated with a window.
+    Unscopes a namespace (un-binds it from the given scope).
-
-    Parameters: ~
-      • {window}  Window handle, or 0 for current window
-
-    Return: ~
-        a list of namespaces ids
-
-nvim_win_remove_ns({window}, {ns_id})                   *nvim_win_remove_ns()*
-    Removes the namespace scope from the window.
 
     Parameters: ~
       • {window}  Window handle, or 0 for current window
@@ -2888,6 +2880,15 @@ nvim_win_remove_ns({window}, {ns_id})                   *nvim_win_remove_ns()*
     Return: ~
         true if the namespace was removed, else false
 
+nvim_win_get_ns({window})                                  *nvim_win_get_ns()*
+    Gets the namespace scopes for a given window.
+
+    Parameters: ~
+      • {window}  Window handle, or 0 for current window
+
+    Return: ~
+        a list of namespaces ids
+
 
 ==============================================================================
 Window Functions                                                  *api-window*

runtime/doc/develop.txt

@@ -383,7 +383,7 @@ Use existing common {verb} names (actions) if possible:
     - enable:       Enables/disables functionality. Signature should be
                     `enable(enable?:boolean, filter?:table)`.
     - eval:         Evaluates an expression
-    - exec:         Executes code
+    - exec:         Executes code, may return a result
     - fmt:          Formats
     - get:          Gets things (often by a query)
     - inspect:      Presents a high-level, often interactive, view
@@ -405,8 +405,8 @@ Do NOT use these deprecated verbs:
     - show:         Redundant with "print", "echo"
     - toggle:       Prefer `enable(not is_enabled())`.
 
-Use consistent names for {noun} (nouns) in API functions: buffer is called
+Use consistent names for {topic} in API functions: buffer is called "buf"
-"buf" everywhere, not "buffer" in some places and "buf" in others.
+everywhere, not "buffer" in some places and "buf" in others.
     - buf:          Buffer
     - chan:         |channel|
     - cmd:          Command
@@ -419,10 +419,10 @@ Use consistent names for {noun} (nouns) in API functions: buffer is called
     - win:          Window
 
 Do NOT use these deprecated nouns:
-    - buffer
+    - buffer        Use "buf" instead
     - callback      Use on_foo instead
-    - command
+    - command       Use "cmd" instead
-    - window
+    - window        Use "win" instead
 
 							*dev-name-events*
 Use the "on_" prefix to name event-handling callbacks and also the interface for
@@ -440,12 +440,15 @@ Example: >
 <
 							*dev-name-api*
 Use this format to name new RPC |API| functions: >
-    nvim_{noun}_{verb}_{arbitrary-qualifiers}
+    nvim_{topic}_{verb}_{arbitrary-qualifiers}
 
-If the function acts on an object then {noun} is the name of that object
+Do not add new nvim_buf/nvim_win/nvim_tabpage APIs, unless you are certain the
-(e.g. "buf" or "win"). If the function operates in a "global" context then
+concept will NEVER be applied to more than one "scope". That is, {topic}
-{noun} is usually omitted (but consider "namespacing" your global operations
+should be the TOPIC ("ns", "extmark", "option", …) that acts on the scope(s)
-with a {noun} that groups functions under a common concept).
+(buf/win/tabpage/global), it should NOT be the scope. Instead the scope should
+be a parameter (typically manifest as mutually-exclusive buf/win/… flags like
+|nvim_get_option_value()|, or less commonly as a `scope: string` field like
+|nvim_get_option_info2()|).
 
 - Example: `nvim_get_keymap('v')` operates in a global context (first
   parameter is not a Buffer). The "get" verb indicates that it gets anything
@@ -455,6 +458,58 @@ with a {noun} that groups functions under a common concept).
   and uses the "del" {verb}.
 
 
+INTERFACE PATTERNS                                      *dev-patterns*
+
+Prefer adding a single `nvim_{topic}_{verb}_…` interface for a given topic.
+
+Example: >
+
+    nvim_ns_add(
+      ns_id: int,
+      filter: {
+        handle: integer (buf/win/tabpage id)
+        scope: "global" | "win" | "buf" | "tabpage"
+      }
+    ): { ok: boolean }
+
+    nvim_ns_get(
+      ns_id: int,
+      filter: {
+        handle: integer (buf/win/tabpage id)
+        scope: "global" | "win" | "buf" | "tabpage"
+      }
+    ): { ids: int[] }
+
+    nvim_ns_del(
+      ns_id: int,
+      filter: {
+        handle: integer (buf/win/tabpage id)
+        scope: "global" | "win" | "buf" | "tabpage"
+      }
+    ): { ok: boolean }
+
+
+Anti-Example:
+
+Creating separate `nvim_xx`, `nvim_buf_xx`, `nvim_win_xx`, and
+`nvim_tabpage_xx`, functions all for the same `xx` topic, requires 4x the
+amount of documentation, tests, boilerplate, and interfaces, which users must
+comprehend, maintainers must maintain, etc. Thus the following is NOT
+recommended (compare these 12(!) functions to the above 3 functions): >
+
+    nvim_add_ns(…)
+    nvim_buf_add_ns(…)
+    nvim_win_add_ns(…)
+    nvim_tabpage_add_ns(…)
+    nvim_del_ns(…)
+    nvim_buf_del_ns(…)
+    nvim_win_del_ns(…)
+    nvim_tabpage_del_ns(…)
+    nvim_get_ns(…)
+    nvim_buf_get_ns(…)
+    nvim_win_get_ns(…)
+    nvim_tabpage_get_ns(…)
+
 API-CLIENT						*dev-api-client*
 
 							*api-client*

runtime/doc/news.txt

@@ -206,7 +206,18 @@ The following new APIs and features were added.
 • |'smoothscroll'| option to scroll by screen line rather than by text line
   when |'wrap'| is set.
 
-• |nvim_buf_set_extmark()| supports inline virtual text.
+• API enhancements
+  • |nvim_buf_set_extmark()| supports inline virtual text.
+  • |nvim_win_text_height()| computes the number of screen lines occupied
+    by a range of text in a given window.
+  • New RPC client type `msgpack-rpc` is added for |nvim_set_client_info()| to
+    support fully MessagePack-RPC compliant clients.
+  • Floating windows can now be hidden by setting `hide` in |nvim_open_win()| or
+    |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).
+    • Extmarks opt-in to this scoping via the `scoped` flag of |nvim_buf_set_extmark()|.
 
 • 'foldtext' now supports virtual text format. |fold-foldtext|
 
@@ -218,9 +229,6 @@ The following new APIs and features were added.
 • |vim.lpeg| and |vim.re| expose the bundled Lpeg expression grammar parser
   and its regex interface.
 
-• |nvim_win_text_height()| computes the number of screen lines occupied
-  by a range of text in a given window.
-
 • Mapping APIs now support abbreviations when mode short-name has suffix "a".
 
 • Better cmdline completion for string option value. |complete-set-option|
@@ -321,15 +329,9 @@ The following new APIs and features were added.
 • Functions that take a severity as an optional parameter (e.g.
   |vim.diagnostic.get()|) now also accept a list of severities |vim.diagnostic.severity|
 
-• New RPC client type `msgpack-rpc` is added for |nvim_set_client_info()| to
-  support fully MessagePack-RPC compliant clients.
-
 • Floating windows can now show footer with new `footer` and `footer_pos`
   config fields. Uses |hl-FloatFooter| by default.
 
-• Floating windows can now be hidden by setting `hide` in |nvim_open_win()| or
-  |nvim_win_set_config()|.
-
 • |:terminal| command now accepts some |:command-modifiers| (specifically
   |:horizontal| and those that affect splitting a window).
 
@@ -360,8 +362,6 @@ The following new APIs and features were added.
 • 'completeopt' option supports "popup" flag to show extra information in a
   floating window.
 
-• |nvim_input_mouse()| supports mouse buttons "x1" and "x2".
-
 • |v_Q-default| and |v_@-default| repeat a register for each line of a linewise
   visual selection.
 
@@ -386,14 +386,8 @@ The following new APIs and features were added.
   using the OSC 8 control sequence, enabling clickable text in supporting
   terminals.
 
-• Added |nvim_tabpage_set_win()| to set the current window of a tabpage.
-
 • Clicking on a tabpage in the tabline with the middle mouse button closes it.
 
-• |namespace| can now have window scopes. |nvim_win_add_ns()|
-
-• |extmarks| option `scoped`: only show the extmarks in its namespace's scope.
-
 • Added built-in |commenting| support.
 
 • |vim.fs.root()| finds project root directories from a list of "root

runtime/lua/vim/_meta/api.lua

@@ -656,8 +656,8 @@ function vim.api.nvim_buf_line_count(buffer) end
 ---             • 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 that indicates that the extmark should only
+---             • scoped: boolean (EXPERIMENTAL) enables "scoping" for the
----               be displayed in the namespace scope. (experimental)
+---               extmark. See `nvim_win_add_ns()`
 --- @return integer
 function vim.api.nvim_buf_set_extmark(buffer, ns_id, line, col, opts) end
 
@@ -2114,10 +2114,11 @@ 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
 
---- Adds the namespace scope to the window.
+--- 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 the namespace to add
+--- @param ns_id integer Namespace
 --- @return boolean
 function vim.api.nvim_win_add_ns(window, ns_id) end
 
@@ -2137,6 +2138,13 @@ 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
@@ -2173,7 +2181,7 @@ function vim.api.nvim_win_get_cursor(window) end
 --- @return integer
 function vim.api.nvim_win_get_height(window) end
 
---- Gets all the namespaces scopes associated with a window.
+--- Gets the namespace scopes for a given window.
 ---
 --- @param window integer Window handle, or 0 for current window
 --- @return integer[]
@@ -2232,13 +2240,6 @@ function vim.api.nvim_win_hide(window) end
 --- @return boolean
 function vim.api.nvim_win_is_valid(window) end
 
---- Removes the namespace scope from the window.
----
---- @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_remove_ns(window, ns_id) end
-
 --- Sets the current buffer in a window, without side effects
 ---
 --- @param window integer Window handle, or 0 for current window

runtime/lua/vim/highlight.lua

@@ -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_remove_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

@@ -489,8 +489,8 @@ Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id, Object start, Object e
 ///                   used together with virt_text.
 ///               - 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 that indicates that the extmark should only be
+///               - scoped: boolean (EXPERIMENTAL) enables "scoping" for the extmark. See
-///                   displayed in the namespace scope. (experimental)
+///                 |nvim_win_add_ns()|
 ///
 /// @param[out]  err   Error details, if any
 /// @return Id of the created/updated extmark
@@ -1215,10 +1215,11 @@ String nvim__buf_debug_extmarks(Buffer buffer, Boolean keys, Boolean dot, Error
   return mt_inspect(buf->b_marktree, keys, dot);
 }
 
-/// Adds the namespace scope to the window.
+/// 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 the namespace to add
+/// @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)
   FUNC_API_SINCE(12)
@@ -1241,7 +1242,7 @@ Boolean nvim_win_add_ns(Window window, Integer ns_id, Error *err)
   return true;
 }
 
-/// Gets all the namespaces scopes associated with a window.
+/// Gets the namespace scopes for a given window.
 ///
 /// @param window Window handle, or 0 for current window
 /// @return a list of namespaces ids
@@ -1262,12 +1263,12 @@ ArrayOf(Integer) nvim_win_get_ns(Window window, Arena *arena, Error *err)
   return rv;
 }
 
-/// Removes the namespace scope from the window.
+/// 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_remove_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);

test/functional/ui/decorations_spec.lua

@@ -5701,7 +5701,7 @@ describe('decorations: window scoped', function()
                           |
     ]]}
 
-    api.nvim_win_remove_ns(0, ns)
+    api.nvim_win_del_ns(0, ns)
 
     screen:expect(noextmarks)
   end)
@@ -5906,7 +5906,7 @@ describe('decorations: window scoped', function()
                           |
     ]]}
 
-    eq(true, api.nvim_win_remove_ns(0, ns))
+    eq(true, api.nvim_win_del_ns(0, ns))
     eq({}, api.nvim_win_get_ns(0))
 
     screen:expect(noextmarks)