From 97c7646501d5cd6f57c57ce30acca89c5b8573ff Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Sun, 12 May 2024 23:12:25 +0200
Subject: refactor(api): nvim_win_xx_ns are EXPERIMENTAL
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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:/…)"
---
 src/nvim/api/extmark.c | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

(limited to 'src')

diff --git a/src/nvim/api/extmark.c b/src/nvim/api/extmark.c
index ef40daf7bb..85cce45560 100644
--- a/src/nvim/api/extmark.c
+++ b/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)
-  FUNC_API_SINCE(12)
+Boolean nvim__win_add_ns(Window window, Integer ns_id, Error *err)
 {
   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)
-  FUNC_API_SINCE(12)
+ArrayOf(Integer) nvim__win_get_ns(Window window, Arena *arena, Error *err)
 {
   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)
-  FUNC_API_SINCE(12)
+Boolean nvim__win_del_ns(Window window, Integer ns_id, Error *err)
 {
   win_T *win = find_window_by_handle(window, err);
   if (!win) {
-- 
cgit