Merge #38402 from justinmk/doc2

runtime/lua/vim/_core/editor.lua

@@ -510,9 +510,8 @@ end
 
 --- Defers calling {fn} until {timeout} ms passes.
 ---
---- Use to do a one-shot timer that calls {fn}
---- Note: The {fn} is |vim.schedule()|d automatically, so API functions are
---- safe to call.
+--- Use to do a one-shot timer that calls {fn}.
+--- Note: The {fn} is |schedule|d automatically, so API functions are safe to call.
 ---@param fn function Callback to call once `timeout` expires
 ---@param timeout integer Number of milliseconds to wait before calling `fn`
 ---@return uv.uv_timer_t timer luv timer object

runtime/lua/vim/_core/ui2.lua

@@ -32,7 +32,7 @@
 ---
 --- There are four special windows/buffers for presenting messages and cmdline:
 --- - "cmd": Cmdline. Also used for 'showcmd', 'showmode', 'ruler', and messages by default.
---- - "msg": Message window, shows fleeting messages useful for 'cmdheight' == 0.
+--- - "msg": Message window, shows ephemeral messages useful for 'cmdheight' == 0.
 --- - "pager": Pager window, shows |:messages| and certain messages that are never "collapsed".
 --- - "dialog": Dialog window, shows modal prompts that expect user input.
 ---

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

runtime/lua/vim/_meta/options.lua

@@ -965,10 +965,7 @@ vim.go.cb = vim.go.clipboard
 --- used.  The command-line will cover the last line of the screen when
 --- shown.
 ---
---- WARNING: `cmdheight=0` is EXPERIMENTAL. Expect some unwanted behaviour.
---- Some 'shortmess' flags and similar mechanism might fail to take effect,
---- causing unwanted hit-enter prompts.  Some informative messages, both
---- from Nvim itself and plugins, will not be displayed.
+--- WARNING: `cmdheight=0` is EXPERIMENTAL. Works better with `ui2` enabled.
 ---
 --- @type integer
 vim.o.cmdheight = 1
@@ -3807,7 +3804,6 @@ vim.go.js = vim.go.joinspaces
 --- 		the action occurred.
 ---
 ---   clean         Remove unloaded buffers from the jumplist.
---- 		EXPERIMENTAL: this flag may change in the future.
 ---
 --- @type string
 vim.o.jumpoptions = "clean"
@@ -6527,7 +6523,7 @@ vim.bo.spf = vim.bo.spellfile
 --- encoding is used, Vim doesn't check it.
 --- How the related spell files are found is explained here: `spell-load`.
 ---
---- If the `spellfile.lua` plugin is active and you use a language name
+--- If the `package-spellfile` plugin is active and you use a language name
 --- for which Vim cannot find the .spl file in 'runtimepath' the plugin
 --- will ask you if you want to download the file.
 ---

runtime/lua/vim/_meta/vimfn.lua

@@ -9717,7 +9717,7 @@ function vim.fn.stridx(haystack, needle, start) end
 --- parsed back with |eval()|.
 ---
 ---   {expr} type  result ~
----   String    "string"
+---   String    `'string'`
 ---   Number    123
 ---   Float    123.123456 or 1.123456e8 or
 ---       `str2float('inf')`

runtime/lua/vim/lsp.lua

@@ -421,11 +421,12 @@ end
 --- Only return configs which attach to the given filetype.
 --- @field filetype? string
 
---- Get LSP configs.
+--- Gets LSP configs.
 ---
---- WARNING:
---- - May eagerly (prematurely!) evaluate config files in 'runtimepath'.
---- - Configs may be in a partial state if they have async properties such as `on_dir()`.
+--- See also [vim.lsp.get_clients()] to get the runtime values of dynamic fields like `root_dir`,
+--- which depend on the current buffer/workspace/etc.
+---
+--- WARNING: May eagerly (prematurely!) evaluate config files in 'runtimepath'.
 ---
 --- @since 14
 --- @param filter? vim.lsp.get_configs.Filter
@@ -437,13 +438,10 @@ function lsp.get_configs(filter)
 
   local configs = {} --- @type vim.lsp.Config[]
 
-  local config_names --- @type string[]
-  if not filter.enabled then
-    config_names = get_config_names()
-  else
-    -- Shortcut filtering enabled configs by directly getting enabled configs
-    config_names = vim.tbl_keys(lsp._enabled_configs)
-  end
+  local config_names = filter.enabled
+      -- Get enabled configs, without resolving other configs.
+      and vim.tbl_keys(lsp._enabled_configs)
+    or get_config_names()
 
   for _, config_name in ipairs(config_names) do
     local config = lsp.config[config_name]
@@ -1163,7 +1161,7 @@ end
 --- Also return uninitialized clients.
 --- @field package _uninitialized? boolean
 
---- Get active clients.
+--- Gets active clients.
 ---
 ---@since 12
 ---

runtime/lua/vim/net.lua

@@ -20,11 +20,8 @@ local M = {}
 ---The HTTP body of the request
 ---@field body string
 
---- Makes an HTTP GET request to the given URL (asynchronous).
----
---- This function is asynchronous (non-blocking), returning immediately and
---- passing the response object to the optional `on_response` handler on
---- completion.
+--- Makes an HTTP GET request to the given URL, asynchronously passing the result to the specified
+--- `on_response`, `outpath` or `outbuf`.
 ---
 --- Examples:
 --- ```lua