docs: news #38464

runtime/lua/vim/_core/shared.lua

@@ -713,8 +713,7 @@ function vim.tbl_add_reverse_lookup(o)
   return o
 end
 
---- Index into a table (first argument) via string keys passed as subsequent arguments.
---- Return `nil` if the key does not exist.
+--- Gets a value from (nested) table `o` given by the sequence of keys `...`, or `nil` if not found.
 ---
 --- Examples:
 ---
@@ -1223,7 +1222,7 @@ do
   ---     `'thread'`, `'userdata'`.
   ---   - (`fun(val:any): boolean, string?`) A function that returns a boolean and an optional
   ---     string message.
-  --- @param optional? boolean Argument is optional (may be omitted)
+  --- @param optional? boolean Parameter is optional (may be omitted or nil)
   --- @param message? string message when validation fails
   --- @overload fun(name: string, val: any, validator: vim.validate.Validator, message: string)
   --- @overload fun(spec: table<string,[any, vim.validate.Validator, boolean|string]>)

runtime/lua/vim/_core/ui2.lua

@@ -43,7 +43,7 @@
 --- Unlike the legacy |hit-enter| prompt, messages exceeding 'cmdheight' are
 --- instead "collapsed", followed by a `[+x]` "spill" indicator, where `x`
 --- indicates the spilled lines. To see the full messages, do either:
---- - ENTER while cmdline is expanded (not in |Insert-mode| and |Terminal-mode|).
+--- - ENTER immediately after interactive |:| cmdline shows a message and returns to |Normal-mode|.
 --- - |g<| at any time.
 
 local api = vim.api

runtime/lua/vim/_meta/api.lua

@@ -2238,6 +2238,7 @@ function vim.api.nvim_set_decoration_provider(ns_id, opts) end
 --- - force: if true force update the highlight group when it exists.
 --- - link: Name of highlight group to link to. `:hi-link`
 --- - sp: color name or "#RRGGBB"
+--- - update: boolean (default false) Update specified attributes only, leave others unchanged.
 --- - altfont: boolean
 --- - blink: boolean
 --- - bold: boolean
@@ -2254,7 +2255,6 @@ function vim.api.nvim_set_decoration_provider(ns_id, opts) end
 --- - underdotted: boolean
 --- - underdouble: boolean
 --- - underline: boolean
---- - update: boolean false by default; true updates only specified attributes, leaving others unchanged.
 function vim.api.nvim_set_hl(ns_id, name, val) end
 
 --- Set active namespace for highlights defined with `nvim_set_hl()`. This can be set for

runtime/lua/vim/_meta/json.lua

@@ -25,8 +25,8 @@ vim.json = {}
 --- (default: `false`)
 --- @field escape_slash? boolean
 ---
---- If non-empty, the returned JSON is formatted with newlines and whitespace, where `indent`
---- defines the whitespace at each nesting level.
+--- If non-empty, each value in a JSON object or array starts on a new line and is prefixed with
+--- `indent` per nesting level. Adds a space after colons. Does not add a final newline.
 --- (default: `""`)
 --- @field indent? string
 ---

runtime/lua/vim/_meta/vimfn.lua

@@ -90,7 +90,7 @@ function vim.fn.api_info() end
 --- @return 0|1
 function vim.fn.append(lnum, text) end
 
---- Like |append()| but append the text in buffer {expr}.
+--- Like |append()| but append the text in buffer {buf}.
 ---
 --- This function works only for loaded buffers.  First call
 --- |bufload()| if needed.

runtime/lua/vim/_meta/vvars.lua

@@ -806,12 +806,14 @@ vim.v.version = ...
 vim.v.versionlong = ...
 
 --- 0 during startup, 1 just before `VimEnter`.
+--- See also `v:vim_did_init`, which is set earlier.
 --- Read-only.
 --- @type integer
 vim.v.vim_did_enter = ...
 
---- 0 during initialization, 1 after sourcing `vimrc` and just
---- before `load-plugins`.
+--- 0 during initialization, 1 after sourcing the user `vimrc`,
+--- just before `load-plugins`.
+--- See also `v:vim_did_enter`, which is set later.
 --- Read-only.
 --- @type integer
 vim.v.vim_did_init = ...

runtime/lua/vim/fs.lua

@@ -1,4 +1,13 @@
 --- @brief <pre>help
+--- *vim.fs.copy()*
+--- Use |filecopy()| or |uv.fs_copyfile()| to performantly copy an existing file.
+---
+--- Example:
+---
+--- >lua
+---   vim.fn.filecopy('foo.txt', 'bar.txt')
+--- <
+---
 --- *vim.fs.exists()*
 --- Use |uv.fs_stat()| to check a file's type, and whether it exists.
 ---

runtime/lua/vim/ui.lua

@@ -23,16 +23,13 @@ local M = {}
 ---
 --- ```lua
 --- vim.ui.select({ 'tabs', 'spaces' }, {
----     prompt = 'Select tabs or spaces:',
----     format_item = function(item)
----         return "I'd like to choose " .. item
----     end,
+---   prompt = 'Select tabs or spaces:',
+---   format_item = function(item)
+---     return ('I choose %s!'):format(item)
+---   end,
 --- }, function(choice)
----     if choice == 'spaces' then
----         vim.o.expandtab = true
----     else
----         vim.o.expandtab = false
----     end
+---   vim.o.expandtab = choice == 'spaces'
+---   vim.print(('Selected "%s" => expandtab=%s'):format(choice, vim.o.expandtab))
 --- end)
 --- ```
 ---