From 68c26b344ba7618a77f666e1d3f7c09e044c1460 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Wed, 1 Apr 2026 17:04:41 -0400 Subject: [PATCH] docs: misc #38584 --- runtime/doc/lsp.txt | 12 ++++++++++- runtime/doc/lua.txt | 37 ++++++++++++++++++++++---------- runtime/doc/news-0.12.txt | 1 + runtime/doc/starting.txt | 13 ++++++----- runtime/doc/treesitter.txt | 25 ++++++++++----------- runtime/lua/vim/_core/shared.lua | 34 +++++++++++++++++++++-------- runtime/lua/vim/lsp/client.lua | 10 +++++++++ runtime/lua/vim/ui.lua | 3 +-- 8 files changed, 93 insertions(+), 42 deletions(-) diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index c80d937835..ee729385df 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -717,7 +717,7 @@ LspProgress *LspProgress* vim.api.nvim_create_autocmd('LspProgress', { buffer = buf, callback = function(ev) local value = ev.data.params.value vim.api.nvim_echo({ { value.message or 'done' } }, false, { - id = 'lsp.' .. ev.data.client_id, + id = 'lsp.' .. ev.data.params.token, kind = 'progress', source = 'vim.lsp', title = value.title, @@ -1724,6 +1724,16 @@ Lua module: vim.lsp.client *lsp-client* 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 +< • {capabilities}? (`lsp.ClientCapabilities`) Map overriding the default capabilities defined by |vim.lsp.protocol.make_client_capabilities()|, diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 4a6addd756..f0454ccfa7 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -2038,13 +2038,22 @@ vim.tbl_count({t}) *vim.tbl_count()* • https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua vim.tbl_deep_extend({behavior}, {...}) *vim.tbl_deep_extend()* - 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) +< Parameters: ~ • {behavior} (`'error'|'keep'|'force'|fun(key:any, prev_value:any?, value:any): any`) @@ -2096,12 +2105,17 @@ vim.tbl_filter({fn}, {t}) *vim.tbl_filter()* (`any[]`) Table of filtered values vim.tbl_get({o}, {...}) *vim.tbl_get()* - 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: >lua - vim.tbl_get({ key = { nested_key = true }}, 'key', 'nested_key') == true - vim.tbl_get({ key = {}}, 'key', 'nested_key') == nil + Note: To set deeply nested keys, see |vim.tbl_deep_extend()|. + + Example: >lua + 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 < Parameters: ~ @@ -2114,6 +2128,7 @@ vim.tbl_get({o}, {...}) *vim.tbl_get()* See also: ~ • |unpack()| + • |vim.tbl_deep_extend()| vim.tbl_isempty({t}) *vim.tbl_isempty()* Checks if a table is empty. diff --git a/runtime/doc/news-0.12.txt b/runtime/doc/news-0.12.txt index e8ccb63777..1e40c783fc 100644 --- a/runtime/doc/news-0.12.txt +++ b/runtime/doc/news-0.12.txt @@ -360,6 +360,7 @@ PLUGINS unrelated Python virtual environments are activated. |provider-python| • |:checkhealth| now checks for an available |vim.ui.open()| handler. +• spellfile.vim : Replaced by |package-spellfile|. STARTUP diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt index e5513bd115..af7532a7f0 100644 --- a/runtime/doc/starting.txt +++ b/runtime/doc/starting.txt @@ -383,13 +383,12 @@ argument. embed and control Nvim via the RPC |API|. If the channel is closed (except by |:detach|), Nvim exits. - Waits for the client ("embedder") to call |nvim_ui_attach()| - before sourcing startup files and reading buffers, so that UIs - can deterministically handle (display) early messages, - dialogs, etc. The client can do other requests before - `nvim_ui_attach` (e.g. `nvim_get_api_info` for feature-detection). - During this pre-startup phase the user config is of course not - available (similar to `--cmd`). + Waits for a client to call |nvim_ui_attach()| before sourcing + startup files and reading buffers, so that UIs can handle + (display) early messages, dialogs, etc. Clients can do other + requests before `nvim_ui_attach` (e.g. `nvim_get_api_info` for + feature-detection). During this pre-startup phase the user + config is of course not available (similar to `--cmd`). Non-UI embedders must pass |--headless|, then startup will continue without waiting for `nvim_ui_attach`: > diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt index e5a87237fe..9f225dc6dd 100644 --- a/runtime/doc/treesitter.txt +++ b/runtime/doc/treesitter.txt @@ -609,23 +609,24 @@ empty `queries/c/injections.scm` file in your 'runtimepath'. ============================================================================== DEFAULTS *treesitter-defaults* - *v_an* -an Selects [count]th parent node. + *treesitter-incremental-selection* + *v_an* +an Selects [count]th parent node. - If buffer has no treesitter parser, - falls back to |vim.lsp.buf.selection_range()|. + If buffer has no treesitter parser, + falls back to |vim.lsp.buf.selection_range()|. - *v_in* -in Selects [count]th previous (or first) child node. + *v_in* +in Selects [count]th previous (or first) child node. - If buffer has no treesitter parser, - falls back to |vim.lsp.buf.selection_range()|. + If buffer has no treesitter parser, + falls back to |vim.lsp.buf.selection_range()|. - *v_]n* -]n Selects [count]th next node. + *v_]n* +]n Selects [count]th next node. - *v_[n* -[n Selects [count]th previous node. + *v_[n* +[n Selects [count]th previous node. ============================================================================== VIM.TREESITTER *lua-treesitter* diff --git a/runtime/lua/vim/_core/shared.lua b/runtime/lua/vim/_core/shared.lua index 9b0b90984a..c4a515fad5 100644 --- a/runtime/lua/vim/_core/shared.lua +++ b/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 diff --git a/runtime/lua/vim/lsp/client.lua b/runtime/lua/vim/lsp/client.lua index 3fd5f0455d..a13ef90da6 100644 --- a/runtime/lua/vim/lsp/client.lua +++ b/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()|, diff --git a/runtime/lua/vim/ui.lua b/runtime/lua/vim/ui.lua index 28ae4bfee0..fc0083251b 100644 --- a/runtime/lua/vim/ui.lua +++ b/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)