From a3b48b1054d01084face54d830f35c7a5a4e35a4 Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Fri, 20 Mar 2026 23:52:42 +0100
Subject: docs: api, plugins, ui2

---
 runtime/lua/vim/_meta/api.lua | 36 ++++++++++++++++++++++++++++++++----
 1 file changed, 32 insertions(+), 4 deletions(-)

(limited to 'runtime/lua/vim/_meta/api.lua')

diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index 2eec5633bc..ccaa6192aa 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -9,17 +9,21 @@ error('Cannot require a meta file')
 
 vim.api = {}
 
+--- WARNING: This feature is experimental/unstable.
+---
 --- @param buffer integer
 --- @param keys boolean
 --- @param dot boolean
 --- @return string
 function vim.api.nvim__buf_debug_extmarks(buffer, keys, dot) end
 
+--- WARNING: This feature is experimental/unstable.
+---
 --- @param buffer integer
 --- @return table<string,any>
 function vim.api.nvim__buf_stats(buffer) end
 
---- EXPERIMENTAL: this API may change in the future.
+--- WARNING: This feature is experimental/unstable.
 ---
 --- 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.
@@ -32,9 +36,13 @@ function vim.api.nvim__buf_stats(buffer) end
 --- - bufnr: (number) buffer id in floating window
 function vim.api.nvim__complete_set(index, opts) end
 
+--- WARNING: This feature is experimental/unstable.
+---
 --- @return string
 function vim.api.nvim__get_lib_dir() end
 
+--- WARNING: This feature is experimental/unstable.
+---
 --- Find files in runtime directories
 ---
 --- @param pat string[] pattern of files to search for
@@ -43,6 +51,8 @@ function vim.api.nvim__get_lib_dir() end
 --- @return string[] # list of absolute paths to the found files
 function vim.api.nvim__get_runtime(pat, all, opts) end
 
+--- WARNING: This feature is experimental/unstable.
+---
 --- Returns object given as argument.
 ---
 --- This API function is used for testing. One should not rely on its presence
@@ -52,6 +62,8 @@ function vim.api.nvim__get_runtime(pat, all, opts) end
 --- @return any # its argument.
 function vim.api.nvim__id(obj) end
 
+--- WARNING: This feature is experimental/unstable.
+---
 --- Returns array given as argument.
 ---
 --- This API function is used for testing. One should not rely on its presence
@@ -61,6 +73,8 @@ function vim.api.nvim__id(obj) end
 --- @return any[] # its argument.
 function vim.api.nvim__id_array(arr) end
 
+--- WARNING: This feature is experimental/unstable.
+---
 --- Returns dict given as argument.
 ---
 --- This API function is used for testing. One should not rely on its presence
@@ -70,6 +84,8 @@ function vim.api.nvim__id_array(arr) end
 --- @return table<string,any> # its argument.
 function vim.api.nvim__id_dict(dct) end
 
+--- WARNING: This feature is experimental/unstable.
+---
 --- Returns floating-point value given as argument.
 ---
 --- This API function is used for testing. One should not rely on its presence
@@ -79,6 +95,8 @@ function vim.api.nvim__id_dict(dct) end
 --- @return number # its argument.
 function vim.api.nvim__id_float(flt) end
 
+--- WARNING: This feature is experimental/unstable.
+---
 --- NB: if your UI doesn't use hlstate, this will not return hlstate first time.
 --- @param grid integer
 --- @param row integer
@@ -86,11 +104,13 @@ function vim.api.nvim__id_float(flt) end
 --- @return any[]
 function vim.api.nvim__inspect_cell(grid, row, col) end
 
+--- WARNING: This feature is experimental/unstable.
+---
 --- 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.
 function vim.api.nvim__invalidate_glyph_cache() end
 
---- EXPERIMENTAL: this API will change in the future.
+--- WARNING: This feature is experimental/unstable.
 ---
 --- Get the properties for namespace
 ---
@@ -98,7 +118,7 @@ function vim.api.nvim__invalidate_glyph_cache() end
 --- @return vim.api.keyset.ns_opts # Map defining the namespace properties, see |nvim__ns_set()|
 function vim.api.nvim__ns_get(ns_id) end
 
---- EXPERIMENTAL: this API will change in the future.
+--- WARNING: This feature is experimental/unstable.
 ---
 --- Set some properties for namespace
 ---
@@ -107,7 +127,7 @@ function vim.api.nvim__ns_get(ns_id) end
 --- - wins: a list of windows to be scoped in
 function vim.api.nvim__ns_set(ns_id, opts) end
 
---- EXPERIMENTAL: this API may change in the future.
+--- WARNING: This feature is experimental/unstable.
 ---
 --- Instruct Nvim to redraw various components.
 ---
@@ -134,17 +154,25 @@ function vim.api.nvim__ns_set(ns_id, opts) end
 --- - tabline: Redraw the 'tabline'.
 function vim.api.nvim__redraw(opts) end
 
+--- WARNING: This feature is experimental/unstable.
+---
 --- @return any[]
 function vim.api.nvim__runtime_inspect() end
 
+--- WARNING: This feature is experimental/unstable.
+---
 --- @param path string
 function vim.api.nvim__screenshot(path) end
 
+--- WARNING: This feature is experimental/unstable.
+---
 --- Gets internal stats.
 ---
 --- @return table<string,any> # Map of various internal stats.
 function vim.api.nvim__stats() end
 
+--- WARNING: This feature is experimental/unstable.
+---
 --- @param str string
 --- @return any
 function vim.api.nvim__unpack(str) end
-- 
cgit