docs(api): sort unreleased nvim__ functions last #28580

4 files changed, 103 insertions, 96 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index e564b19fc3..d15230ba2d 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -584,99 +584,6 @@ 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
-
-    Attributes: ~
-        |api-fast|
-
-    Parameters: ~
-      • {pat}   pattern of files to search for
-      • {all}   whether to return all matches or only the first
-      • {opts}  is_lua: only search Lua subdirs
-
-    Return: ~
-        list of absolute paths to the found files
-
-nvim__id({obj})                                                   *nvim__id()*
-    Returns object given as argument.
-
-    This API function is used for testing. One should not rely on its presence
-    in plugins.
-
-    Parameters: ~
-      • {obj}  Object to return.
-
-    Return: ~
-        its argument.
-
-nvim__id_array({arr})                                       *nvim__id_array()*
-    Returns array given as argument.
-
-    This API function is used for testing. One should not rely on its presence
-    in plugins.
-
-    Parameters: ~
-      • {arr}  Array to return.
-
-    Return: ~
-        its argument.
-
-nvim__id_dictionary({dct})                             *nvim__id_dictionary()*
-    Returns dictionary given as argument.
-
-    This API function is used for testing. One should not rely on its presence
-    in plugins.
-
-    Parameters: ~
-      • {dct}  Dictionary to return.
-
-    Return: ~
-        its argument.
-
-nvim__id_float({flt})                                       *nvim__id_float()*
-    Returns floating-point value given as argument.
-
-    This API function is used for testing. One should not rely on its presence
-    in plugins.
-
-    Parameters: ~
-      • {flt}  Value to return.
-
-    Return: ~
-        its argument.
-
-nvim__inspect_cell({grid}, {row}, {col})                *nvim__inspect_cell()*
-    NB: if your UI doesn't use hlstate, this will not return hlstate first
-    time.
-
-nvim__invalidate_glyph_cache()                *nvim__invalidate_glyph_cache()*
-    For testing. The condition in schar_cache_clear_if_full is hard to reach,
-    so this function can be used to force a cache clear in a test.
-
-nvim__stats()                                                  *nvim__stats()*
-    Gets internal stats.
-
-    Return: ~
-        Map of various internal stats.
-
 nvim_chan_send({chan}, {data})                              *nvim_chan_send()*
     Send data to channel `id`. For a job, it writes it to the stdin of the
     process. For the stdio channel |channel-stdio|, it writes to Nvim's
@@ -1572,6 +1479,99 @@ nvim_unsubscribe({event})                                 *nvim_unsubscribe()*
     Parameters: ~
       • {event}  Event type string
 
+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
+
+    Attributes: ~
+        |api-fast|
+
+    Parameters: ~
+      • {pat}   pattern of files to search for
+      • {all}   whether to return all matches or only the first
+      • {opts}  is_lua: only search Lua subdirs
+
+    Return: ~
+        list of absolute paths to the found files
+
+nvim__id({obj})                                                   *nvim__id()*
+    Returns object given as argument.
+
+    This API function is used for testing. One should not rely on its presence
+    in plugins.
+
+    Parameters: ~
+      • {obj}  Object to return.
+
+    Return: ~
+        its argument.
+
+nvim__id_array({arr})                                       *nvim__id_array()*
+    Returns array given as argument.
+
+    This API function is used for testing. One should not rely on its presence
+    in plugins.
+
+    Parameters: ~
+      • {arr}  Array to return.
+
+    Return: ~
+        its argument.
+
+nvim__id_dictionary({dct})                             *nvim__id_dictionary()*
+    Returns dictionary given as argument.
+
+    This API function is used for testing. One should not rely on its presence
+    in plugins.
+
+    Parameters: ~
+      • {dct}  Dictionary to return.
+
+    Return: ~
+        its argument.
+
+nvim__id_float({flt})                                       *nvim__id_float()*
+    Returns floating-point value given as argument.
+
+    This API function is used for testing. One should not rely on its presence
+    in plugins.
+
+    Parameters: ~
+      • {flt}  Value to return.
+
+    Return: ~
+        its argument.
+
+nvim__inspect_cell({grid}, {row}, {col})                *nvim__inspect_cell()*
+    NB: if your UI doesn't use hlstate, this will not return hlstate first
+    time.
+
+nvim__invalidate_glyph_cache()                *nvim__invalidate_glyph_cache()*
+    For testing. The condition in schar_cache_clear_if_full is hard to reach,
+    so this function can be used to force a cache clear in a test.
+
+nvim__stats()                                                  *nvim__stats()*
+    Gets internal stats.
+
+    Return: ~
+        Map of various internal stats.
+
 
 ==============================================================================
 Vimscript Functions                                            *api-vimscript*
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index 58fa9af8cd..d799446647 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -24,7 +24,7 @@ function vim.api.nvim__buf_redraw_range(buffer, first, last) end
 function vim.api.nvim__buf_stats(buffer) end
 
 --- @private
---- EXPERIMENTAL: this api may change in the future.
+--- 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
diff --git a/scripts/gen_vimdoc.lua b/scripts/gen_vimdoc.lua
index cc2dc99237..085b1f5bea 100755
--- a/scripts/gen_vimdoc.lua
+++ b/scripts/gen_vimdoc.lua
@@ -768,10 +768,17 @@ local function render_funs(funs, classes, cfg)
     ret[#ret + 1] = render_fun(f, classes, cfg)
   end
 
-  -- Sort via prototype
+  -- Sort via prototype. Experimental API functions ("nvim__") sort last.
   table.sort(ret, function(a, b)
     local a1 = ('\n' .. a):match('\n[a-zA-Z_][^\n]+\n')
     local b1 = ('\n' .. b):match('\n[a-zA-Z_][^\n]+\n')
+
+    local a1__ = a1:find('^%s*nvim__') and 1 or 0
+    local b1__ = b1:find('^%s*nvim__') and 1 or 0
+    if a1__ ~= b1__ then
+      return a1__ < b1__
+    end
+
     return a1:lower() < b1:lower()
   end)
 
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 8458611ee8..e75f4e629b 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -2282,7 +2282,7 @@ 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 : "");
 }
 
-/// EXPERIMENTAL: this api may change in the future.
+/// 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.