From e3a1e47bb27bec28dd3b2cf17762157ce5007889 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Wed, 18 Mar 2026 23:53:55 +0100 Subject: [PATCH 1/3] docs: misc --- runtime/doc/lsp.txt | 8 +++++++- runtime/doc/lua-guide.txt | 6 ------ runtime/doc/lua.txt | 8 ++++---- runtime/doc/news.txt | 8 +++----- runtime/doc/treesitter.txt | 5 +++-- runtime/doc/vimeval.txt | 2 +- runtime/doc/vimfn.txt | 2 +- runtime/example_init.lua | 5 +++++ runtime/lua/vim/_core/editor.lua | 2 +- runtime/lua/vim/_meta/vimfn.lua | 2 +- runtime/lua/vim/lsp.lua | 6 +++++- runtime/lua/vim/treesitter/_meta/tsnode.lua | 4 ++-- runtime/lua/vim/ui.lua | 20 ++++++++------------ src/gen/gen_help_html.lua | 3 --- src/nvim/eval.lua | 2 +- src/nvim/message.c | 1 + src/nvim/path.c | 2 +- test/functional/ex_cmds/menu_spec.lua | 1 + 18 files changed, 45 insertions(+), 42 deletions(-) diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index d47d4f6ded..fdb66ff45a 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -1157,7 +1157,13 @@ get_clients({filter}) *vim.lsp.get_clients()* get_configs({filter}) *vim.lsp.get_configs()* Get LSP configs. - Note: Will eagerly evaluate config files in `'runtimepath'` if necessary. + 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()`. + + Attributes: ~ + Since: 0.12.0 Parameters: ~ • {filter} (`table?`) Key-value pairs used to filter the returned diff --git a/runtime/doc/lua-guide.txt b/runtime/doc/lua-guide.txt index 776126b667..09e3f452f4 100644 --- a/runtime/doc/lua-guide.txt +++ b/runtime/doc/lua-guide.txt @@ -160,7 +160,6 @@ the cache manually first: package.loaded['myluamodule'] = nil require('myluamodule') -- read and execute the module again from disk < ------------------------------------------------------------------------------- See also: • |lua-module-load|: how `require()` finds modules • |pcall()| @@ -228,7 +227,6 @@ e.g., |autoload| functions have to be called with this syntax: >lua vim.fn['my#autoload#function']() < ------------------------------------------------------------------------------- See also: • |vimscript-functions|: descriptions of all Vimscript functions • |function-list|: Vimscript functions grouped by topic @@ -287,7 +285,6 @@ To delete a variable, simply set it to `nil`: >lua vim.g.myvar = nil < ------------------------------------------------------------------------------- See also: • |lua-vim-variables| @@ -384,7 +381,6 @@ window is used: -- in current window only print(vim.wo[0].number) --> true < ------------------------------------------------------------------------------- See also: • |lua-options| @@ -473,7 +469,6 @@ A specific mapping can be removed with |vim.keymap.del()|: vim.keymap.del('n', 'ex1') vim.keymap.del({'n', 'c'}, 'ex2', {buffer = true}) < ------------------------------------------------------------------------------- See also: • `vim.api.`|nvim_get_keymap()|: return all global mapping • `vim.api.`|nvim_buf_get_keymap()|: return all mappings for buffer @@ -646,7 +641,6 @@ the autocommands that are to be removed: Note: Autocommands in groups will only be removed if the `group` key is specified, even if another option matches it. ------------------------------------------------------------------------------- See also • |nvim_get_autocmds()|: return all matching autocommands • |nvim_exec_autocmds()|: execute all matching autocommands diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 77fb305524..d5c954667c 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -1304,7 +1304,7 @@ vim.deprecate({name}, {alternative}, {version}, {plugin}, {backtrace}) • {backtrace} (`boolean?`) Prints backtrace. Defaults to true. Return: ~ - (`string?`) Deprecated message, or nil if no message was shown. + (`string?`) Deprecation message, or nil if no message was shown. vim.inspect() *vim.inspect()* Gets a human-readable representation of the given object. @@ -5032,11 +5032,11 @@ vim.ui.open({path}, {opt}) *vim.ui.open()* • |vim.system()| vim.ui.progress_status() *vim.ui.progress_status()* - Gets the status of currently running progress messages, in a format - convenient for inclusion in 'statusline'. + Gets a status description summarizing currently running progress messages. + Convenient for inclusion in 'statusline'. Return: ~ - (`string`) formatted text of progress status for statusline + (`string`) Progress status vim.ui.select({items}, {opts}, {on_choice}) *vim.ui.select()* Prompts the user to pick from a list of items, allowing arbitrary diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index ce7bb8240b..ef9f0eb5dc 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -157,8 +157,6 @@ API • |vim.secure.read()| now returns `true` for trusted directories. Previously it would return `nil`, thus impossible to tell if the directory was actually trusted. -• Added |vim.lsp.is_enabled()| to check if a given LSP config has been enabled - by |vim.lsp.enable()|. • |nvim_ui_send()| writes arbitrary data to a UI's stdout. Use this to write escape sequences to the terminal when Nvim is running in the |TUI|. • |nvim_echo()| can set the |ui-messages| kind with which to emit the message. @@ -281,6 +279,7 @@ LSP non-applicable LSP clients. • |vim.lsp.is_enabled()| checks if a LSP config is enabled (without "resolving" it). +• |vim.lsp.get_configs()| gets all LSP configs matching an optional filter. • Support for `workspace/diagnostic`: |vim.lsp.buf.workspace_diagnostics()| https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_dagnostics • Incremental selection is now supported via `textDocument/selectionRange`. @@ -331,7 +330,6 @@ LSP • Support for `workspace/codeLens/refresh`: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#codeLens_refresh • |gx| opens `textDocument/documentLink` items found at cursor. -• |vim.lsp.get_configs()| can get all LSP configs matching certain conditions. LUA @@ -466,8 +464,8 @@ UI • Cursor shape indicates when it is behind an unfocused floating window. • Improved LSP signature help rendering. • Multigrid UIs can call nvim_input_mouse with grid 0 to let Nvim decide the grid. -• |vim.ui.progress_status()| returns a formatted string of currently -running |progress-message|. +• |vim.ui.progress_status()| returns a status description of currently running + |progress-message|s. VIMSCRIPT diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt index 1e8429060d..4ebbde3be3 100644 --- a/runtime/doc/treesitter.txt +++ b/runtime/doc/treesitter.txt @@ -671,8 +671,9 @@ TSTree:root() *TSTree:root()* TREESITTER NODES *treesitter-node* *TSNode* A "treesitter node" represents one specific element of the parsed contents of -a buffer, which can be captured by a |Query| for, e.g., highlighting. It is a -|userdata| reference to an object held by the treesitter library. +a buffer, which can be captured by a |treesitter-query| for, e.g., +highlighting. It is a |userdata| reference to an object held by the treesitter +library. An instance `TSNode` of a treesitter node supports the following methods. diff --git a/runtime/doc/vimeval.txt b/runtime/doc/vimeval.txt index 6805ead2db..393b5c6a27 100644 --- a/runtime/doc/vimeval.txt +++ b/runtime/doc/vimeval.txt @@ -1436,7 +1436,7 @@ The sequence must be an even number of hex characters. Example: > ------------------------------------------------------------------------------ literal-string *literal-string* *E115* -'string' string constant *expr-'* +`'string'` string constant *expr-'* Note that single quotes are used. diff --git a/runtime/doc/vimfn.txt b/runtime/doc/vimfn.txt index 4f8a357de4..36538ab11a 100644 --- a/runtime/doc/vimfn.txt +++ b/runtime/doc/vimfn.txt @@ -10650,7 +10650,7 @@ string({expr}) *string()* parsed back with |eval()|. {expr} type result ~ - String 'string' + String "string" Number 123 Float 123.123456 or 1.123456e8 or `str2float('inf')` diff --git a/runtime/example_init.lua b/runtime/example_init.lua index e2a455a542..e4c0b016ed 100644 --- a/runtime/example_init.lua +++ b/runtime/example_init.lua @@ -100,3 +100,8 @@ vim.pack.add({ -- Git integration 'https://github.com/lewis6991/gitsigns.nvim', }) + +require('fzf-lua').setup({ fzf_colors = true }) +require('mini.completion').setup {} +require('quicker').setup {} +require('gitsigns').setup {} diff --git a/runtime/lua/vim/_core/editor.lua b/runtime/lua/vim/_core/editor.lua index c967727336..202a5a4da4 100644 --- a/runtime/lua/vim/_core/editor.lua +++ b/runtime/lua/vim/_core/editor.lua @@ -1256,7 +1256,7 @@ end --- Defaults to "Nvim". ---@param backtrace boolean|nil Prints backtrace. Defaults to true. --- ----@return string|nil # Deprecated message, or nil if no message was shown. +---@return string|nil # Deprecation message, or nil if no message was shown. function vim.deprecate(name, alternative, version, plugin, backtrace) plugin = plugin or 'Nvim' if plugin == 'Nvim' then diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index d975163af8..d10687cc26 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/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')` diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua index 30ce7eabd8..4c42b30391 100644 --- a/runtime/lua/vim/lsp.lua +++ b/runtime/lua/vim/lsp.lua @@ -423,7 +423,11 @@ end --- Get LSP configs. --- ---- Note: Will eagerly evaluate config files in `'runtimepath'` if necessary. +--- 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()`. +--- +--- @since 14 --- @param filter? vim.lsp.get_configs.Filter --- @return vim.lsp.Config[]: List of |vim.lsp.Config| objects function lsp.get_configs(filter) diff --git a/runtime/lua/vim/treesitter/_meta/tsnode.lua b/runtime/lua/vim/treesitter/_meta/tsnode.lua index de4b71c697..fb7d133f7a 100644 --- a/runtime/lua/vim/treesitter/_meta/tsnode.lua +++ b/runtime/lua/vim/treesitter/_meta/tsnode.lua @@ -3,8 +3,8 @@ error('Cannot require a meta file') --- @brief A "treesitter node" represents one specific element of the parsed contents of a buffer, ---- which can be captured by a |Query| for, e.g., highlighting. It is a |userdata| reference to an ---- object held by the treesitter library. +--- which can be captured by a |treesitter-query| for, e.g., highlighting. It is a |userdata| +--- reference to an object held by the treesitter library. --- --- An instance `TSNode` of a treesitter node supports the following methods. diff --git a/runtime/lua/vim/ui.lua b/runtime/lua/vim/ui.lua index f891ba9754..401334d00c 100644 --- a/runtime/lua/vim/ui.lua +++ b/runtime/lua/vim/ui.lua @@ -322,7 +322,7 @@ do -- store progress events local progress_group, progress_autocmd = nil, nil - ---Initialize progress event listeners + --- Initialize Progress handlers. local function progress_init() progress_group = vim.api.nvim_create_augroup('nvim.ui.progress_status', { clear = true }) progress_autocmd = vim.api.nvim_create_autocmd('Progress', { @@ -333,12 +333,8 @@ do if not ev.data or not ev.data.id then return end - progress[ev.data.id] = { - id = ev.data.id, - title = ev.data.title, - status = ev.data.status, - percent = ev.data.percent or 0, - } + ev.data.percent = ev.data.percent or 0 + progress[ev.data.id] = ev.data -- Clear finished items if @@ -353,7 +349,7 @@ do }) end - ---Return statusline text summarizing progress messages. + --- 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: N items AVG%" @@ -379,11 +375,11 @@ do end end - --- Gets the status of currently running progress messages, in a format - --- convenient for inclusion in 'statusline'. - ---@return string formatted text of progress status for statusline + --- Gets a status description summarizing currently running progress messages. + --- Convenient for inclusion in 'statusline'. + --- + ---@return string # Progress status function M.progress_status() - -- Create progress event listener on first call if progress_autocmd == nil then progress_init() end diff --git a/src/gen/gen_help_html.lua b/src/gen/gen_help_html.lua index c46dbfe589..1bf269b185 100644 --- a/src/gen/gen_help_html.lua +++ b/src/gen/gen_help_html.lua @@ -117,10 +117,7 @@ local redirects = { -- TODO: These known invalid |links| require an update to the relevant docs. local exclude_invalid = { - ["'string'"] = 'vimeval.txt', - Query = 'treesitter.txt', matchit = 'vim_diff.txt', - ['set!'] = 'treesitter.txt', } -- False-positive "invalid URLs". diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua index 60afb158ab..21a08452bb 100644 --- a/src/nvim/eval.lua +++ b/src/nvim/eval.lua @@ -11713,7 +11713,7 @@ M.funcs = { parsed back with |eval()|. {expr} type result ~ - String 'string' + String "string" Number 123 Float 123.123456 or 1.123456e8 or `str2float('inf')` diff --git a/src/nvim/message.c b/src/nvim/message.c index 3342c53fc5..e68b0dff10 100644 --- a/src/nvim/message.c +++ b/src/nvim/message.c @@ -362,6 +362,7 @@ static HlMessage format_progress_message(HlMessage hl_msg, MessageData *msg_data MsgID msg_multihl(MsgID id, HlMessage hl_msg, const char *kind, bool history, bool err, MessageData *msg_data, bool *needs_msg_clear) { + // Message `id`: // - Nil: Generate a new Integer id. // - Integer: Existing id. // - String: User-defined id (new or existing). diff --git a/src/nvim/path.c b/src/nvim/path.c index fe8fe651d8..ad12b39079 100644 --- a/src/nvim/path.c +++ b/src/nvim/path.c @@ -2380,7 +2380,7 @@ static int path_to_absolute(const char *fname, char *buf, size_t len, int force) if (p == NULL) { p = strrchr(fname, '\\'); } - if (p == NULL && ASCII_ISALPHA(fname[0]) && fname[1] == ':') { + if (p == NULL && ASCII_ISALPHA(fname[0]) && fname[1] == ':') { // drive letter p = fname + 1; } #endif diff --git a/test/functional/ex_cmds/menu_spec.lua b/test/functional/ex_cmds/menu_spec.lua index 72f686c839..5276fc2d2d 100644 --- a/test/functional/ex_cmds/menu_spec.lua +++ b/test/functional/ex_cmds/menu_spec.lua @@ -66,6 +66,7 @@ describe(':emenu', function() feed('itextV') command('emenu PopUp.Cut') eq('', fn.getline(1)) + eq('text\n', fn.getreg('"')) eq('', n.api.nvim_get_vvar('errmsg')) end) end) From 2ce6d1b11825684f0c0374d67d612ab9738a1b74 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Thu, 19 Mar 2026 10:56:54 +0100 Subject: [PATCH 2/3] refactor(build): Makefile readability --- Makefile | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Makefile b/Makefile index 3971bdd0fa..590bda7178 100644 --- a/Makefile +++ b/Makefile @@ -112,17 +112,18 @@ build/.ran-cmake: | deps $(CMAKE) -B build -G $(CMAKE_GENERATOR) $(CMAKE_FLAGS) $(CMAKE_EXTRA_FLAGS) $(MAKEFILE_DIR) $(TOUCH) $@ +ifneq ($(call filter-true,$(USE_BUNDLED)),) +deps: ; +else deps: | build/.ran-deps-cmake -ifeq ($(call filter-true,$(USE_BUNDLED)),) $(CMAKE) --build $(DEPS_BUILD_DIR) -endif -ifeq ($(call filter-true,$(USE_BUNDLED)),) $(DEPS_BUILD_DIR): $(MKDIR) $@ build/.ran-deps-cmake:: $(DEPS_BUILD_DIR) $(CMAKE) -S $(MAKEFILE_DIR)/cmake.deps -B $(DEPS_BUILD_DIR) -G $(CMAKE_GENERATOR) $(DEPS_CMAKE_FLAGS) endif + build/.ran-deps-cmake:: $(MKDIR) build $(TOUCH) "$@" @@ -136,6 +137,7 @@ else @# Handle TEST_FILE=test_foo{,.res,.vim}. $(SINGLE_MAKE) -C test/old/testdir NVIM_PRG=$(NVIM_PRG) SCRIPTS= $(MAKEOVERRIDES) $(patsubst %.vim,%,$(patsubst %.res,%,$(TEST_FILE))) endif + # Build oldtest by specifying the relative .vim filename. .PHONY: phony_force test/old/testdir/%.vim: phony_force nvim From 30f120ebc1f9dd7d0cb662ac5432c36a9164fb85 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Thu, 19 Mar 2026 13:24:22 +0100 Subject: [PATCH 3/3] build(clangd): docstrings are Doxygen Problem: clangd treats our docstrings as Plaintext. Solution: Update `.clangd`. --- .clangd | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.clangd b/.clangd index 1bb663fd8b..9a99bd1d04 100644 --- a/.clangd +++ b/.clangd @@ -2,3 +2,5 @@ CompileFlags: CompilationDatabase: build/ # Search build/ directory for compile_commands.json Diagnostics: UnusedIncludes: None +Documentation: + CommentFormat: Doxygen