backport: docs: misc #38692

runtime/lua/vim/_core/shared.lua

@@ -628,12 +628,22 @@ function vim.tbl_extend(behavior, ...)
   return tbl_extend(behavior, false, ...)
 end
 
---- Merges recursively two or more tables.
+--- Merges two or more tables recursively.
 ---
---- Only values that are empty tables or tables that are not |lua-list|s (indexed by consecutive
---- integers starting from 1) are merged recursively. This is useful for merging nested tables
---- like default and user configurations where lists should be treated as literals (i.e., are
---- overwritten instead of merged).
+--- Only |lua-dict| tables are merged recursively; |lua-list| tables are treated as opaque values
+--- (overwritten instead of merged). That is convenient for merging default/user configurations
+--- where lists typically should not be merged together.
+---
+--- Example:
+--- ```lua
+--- -- Set `config.settings.…` without worrying about whether intermediate dicts exist.
+--- local config = { settings = { tailwindCSS = { foo = 'bar' } } }
+--- local merged = vim.tbl_deep_extend('force',
+---   config,
+---   { settings = { tailwindCSS = { experimental = { configFile = '/my/config.json' } } } }
+--- )
+--- vim.print(merged)
+--- ```
 ---
 ---@see |vim.tbl_extend()|
 ---
@@ -713,15 +723,21 @@ function vim.tbl_add_reverse_lookup(o)
   return o
 end
 
---- Gets a value from (nested) table `o` given by the sequence of keys `...`, or `nil` if not found.
+--- Gets a (nested) value from table `o` given by a sequence of keys `...`, or `nil` if not found.
 ---
---- Examples:
+--- Note: To _set_ deeply nested keys, see |vim.tbl_deep_extend()|.
 ---
+--- Example:
 --- ```lua
---- vim.tbl_get({ key = { nested_key = true }}, 'key', 'nested_key') == true
---- vim.tbl_get({ key = {}}, 'key', 'nested_key') == nil
+--- local o = { a = { b = true } }
+--- -- Get `o.a.b`.
+--- vim.print(vim.tbl_get(o, 'a', 'b')) -- true
+--- o.a = {}
+--- vim.print(vim.tbl_get(o, 'a', 'b')) -- nil
 --- ```
+---
 ---@see |unpack()|
+---@see |vim.tbl_deep_extend()|
 ---
 ---@param o table Table to index
 ---@param ... any Optional keys (0 or more, variadic) via which to index the table

runtime/lua/vim/lsp/client.lua

@@ -30,6 +30,16 @@ local all_clients = {}
 --- Callback which can modify parameters before they are sent to the server. Invoked before LSP
 --- "initialize" phase (after `cmd` is invoked), where `params` is the parameters being sent to the
 --- server and `config` is the config passed to |vim.lsp.start()|.
+---
+--- Hint: use |vim.tbl_deep_extend()| to set nested fields easily.
+--- ```lua
+--- before_init = function(_, config)
+---   config.settings = vim.tbl_deep_extend('force',
+---     config.settings,
+---     { tailwindCSS = { experimental = { configFile = find_tailwind_global_css() } } }
+---   )
+--- end
+--- ```
 --- @field before_init? fun(params: lsp.InitializeParams, config: vim.lsp.ClientConfig)
 ---
 --- Map overriding the default capabilities defined by |vim.lsp.protocol.make_client_capabilities()|,

runtime/lua/vim/ui.lua

@@ -348,8 +348,7 @@ do
 
   --- Gets a status description summarizing currently running progress messages.
   --- - If none: returns empty string
-  --- - If one running item: "title: 42%"
-  --- - If multiple running items: "Progress: AVG%(N)"
+  --- - If N item running: "AVG%(N)"
   ---@param running ProgressMessage[]
   ---@return string
   local function progress_status_fmt(running)