fix(api): mark nvim__complete_set as experimental #28579

Problem:
nvim_complete_set was added in 5ed55ff14c
but needs more bake time.

Solution:
Rename it, mark it as experimental.

runtime/doc/api.txt

@@ -584,6 +584,23 @@ created for extmark changes.
 ==============================================================================
 Global Functions                                                  *api-global*
 
+nvim__complete_set({index}, {opts})                     *nvim__complete_set()*
+    EXPERIMENTAL: this api may change in the future.
+
+    Sets info for the completion item at the given index. If the info text was
+    shown in a window, returns the window and buffer ids, or empty dict if not
+    shown.
+
+    Parameters: ~
+      • {index}  Completion candidate index
+      • {opts}   Optional parameters.
+                 • info: (string) info text.
+
+    Return: ~
+        Dictionary containing these keys:
+        • winid: (number) floating window id
+        • bufnr: (number) buffer id in floating window
+
 nvim__get_runtime({pat}, {all}, {opts})                  *nvim__get_runtime()*
     Find files in runtime directories
 
@@ -678,21 +695,6 @@ nvim_chan_send({chan}, {data})                              *nvim_chan_send()*
       • {chan}  id of the channel
       • {data}  data to write. 8-bit clean: can contain NUL bytes.
 
-nvim_complete_set({index}, {opts})                       *nvim_complete_set()*
-    Set info for the completion candidate index. if the info was shown in a
-    window, then the window and buffer ids are returned for further
-    customization. If the text was not shown, an empty dict is returned.
-
-    Parameters: ~
-      • {index}  the completion candidate index
-      • {opts}   Optional parameters.
-                 • info: (string) info text.
-
-    Return: ~
-        Dictionary containing these keys:
-        • winid: (number) floating window id
-        • bufnr: (number) buffer id in floating window
-
 nvim_create_buf({listed}, {scratch})                       *nvim_create_buf()*
     Creates a new, empty, unnamed buffer.
 

runtime/doc/news.txt

@@ -174,6 +174,9 @@ cycle (Nvim HEAD, the "master" branch).
 
 • Removed Iter:nthback(), use Iter:nth() with negative index instead.
 
+• Renamed nvim_complete_set to nvim__complete_set and marked it as
+  experimental.
+
 ==============================================================================
 NEW FEATURES                                                    *news-features*
 

runtime/lua/vim/_meta/api.lua

@@ -23,6 +23,19 @@ function vim.api.nvim__buf_redraw_range(buffer, first, last) end
 --- @return table<string,any>
 function vim.api.nvim__buf_stats(buffer) end
 
+--- @private
+--- EXPERIMENTAL: this api may change in the future.
+---
+--- Sets info for the completion item at the given index. If the info text was
+--- shown in a window, returns the window and buffer ids, or empty dict if not
+--- shown.
+---
+--- @param index integer Completion candidate index
+--- @param opts vim.api.keyset.complete_set Optional parameters.
+---             • info: (string) info text.
+--- @return table<string,any>
+function vim.api.nvim__complete_set(index, opts) end
+
 --- @private
 --- @return string
 function vim.api.nvim__get_lib_dir() end
@@ -822,16 +835,6 @@ function vim.api.nvim_command(command) end
 --- @return string
 function vim.api.nvim_command_output(command) end
 
---- Set info for the completion candidate index. if the info was shown in a
---- window, then the window and buffer ids are returned for further
---- customization. If the text was not shown, an empty dict is returned.
----
---- @param index integer the completion candidate index
---- @param opts vim.api.keyset.complete_set Optional parameters.
----             • info: (string) info text.
---- @return table<string,any>
-function vim.api.nvim_complete_set(index, opts) end
-
 --- Create or get an autocommand group `autocmd-groups`.
 ---
 --- To get an existing group id, do:

src/nvim/api/vim.c

@@ -2282,20 +2282,18 @@ void nvim_error_event(uint64_t channel_id, Integer lvl, String data)
   ELOG("async error on channel %" PRId64 ": %s", channel_id, data.size ? data.data : "");
 }
 
-/// Set info for the completion candidate index.
+/// EXPERIMENTAL: this api may change in the future.
-/// if the info was shown in a window, then the
-/// window and buffer ids are returned for further
-/// customization. If the text was not shown, an
-/// empty dict is returned.
 ///
-/// @param index  the completion candidate index
+/// Sets info for the completion item at the given index. If the info text was shown in a window,
+/// returns the window and buffer ids, or empty dict if not shown.
+///
+/// @param index  Completion candidate index
 /// @param opts   Optional parameters.
 ///       - info: (string) info text.
 /// @return Dictionary containing these keys:
 ///       - winid: (number) floating window id
 ///       - bufnr: (number) buffer id in floating window
-Dictionary nvim_complete_set(Integer index, Dict(complete_set) *opts, Arena *arena)
+Dictionary nvim__complete_set(Integer index, Dict(complete_set) *opts, Arena *arena)
-  FUNC_API_SINCE(12)
 {
   Dictionary rv = arena_dict(arena, 2);
   if (HAS_KEY(opts, complete_set, info)) {

src/nvim/popupmenu.c

@@ -732,7 +732,7 @@ static void pum_adjust_info_position(win_T *wp, int height, int width)
   win_config_float(wp, wp->w_config);
 }
 
-/// Used for nvim_complete_set
+/// Used for nvim__complete_set
 ///
 /// @param selected the selected compl item.
 /// @parma info     Info string.

test/functional/ui/popupmenu_spec.lua

@@ -1608,7 +1608,7 @@ describe('builtin popupmenu', function()
           funct Set_info()
             let comp_info = complete_info()
             if comp_info['selected'] == 2
-              call nvim_complete_set(comp_info['selected'], {"info": "3info"})
+              call nvim__complete_set(comp_info['selected'], {"info": "3info"})
             endif
           endfunc
           autocmd CompleteChanged * call Set_info()
@@ -1728,7 +1728,7 @@ describe('builtin popupmenu', function()
           }
         end
 
-        -- test nvim_complete_set_info
+        -- test nvim__complete_set_info
         feed('<ESC>cc<C-X><C-O><C-N><C-N>')
         vim.uv.sleep(10)
         if multigrid then