From 354ea3bf2a3a11b69fb5eac78b6334e8131ce4c4 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 23 Aug 2026 12:38:07 -0400 Subject: [PATCH] docs: misc #41452 Co-authored-by: darkdi Co-authored-by: Qiaoxi Guo <28090444+breadtitor@users.noreply.github.com> Co-authored-by: zaveshaa --- runtime/doc/api.txt | 21 +++--- runtime/doc/autocmd.txt | 3 +- runtime/doc/cmdline.txt | 2 +- runtime/doc/lua.txt | 2 +- runtime/doc/plugins.txt | 104 +++++++++++++++--------------- runtime/doc/repeat.txt | 3 +- runtime/lua/vim/_core/ui2.lua | 2 +- runtime/lua/vim/_meta/api.gen.lua | 15 +++-- runtime/lua/vim/lsp/sync.lua | 2 +- src/nvim/api/autocmd.c | 6 +- src/nvim/api/buffer.c | 9 +-- src/nvim/eval/typval.c | 2 +- src/nvim/eval/typval.h | 2 +- src/nvim/lua/converter.c | 2 +- src/nvim/marktree.c | 2 +- src/nvim/option.c | 2 +- src/nvim/register.c | 2 +- src/nvim/runtime.c | 2 +- 18 files changed, 97 insertions(+), 86 deletions(-) diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 3a1057836b..3799c77909 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -391,7 +391,8 @@ was changed. The parameters received are ("changedtick", {buf}, {changedtick}). *api-lua-detach* In-process Lua callbacks can detach by returning `true`. This will detach all -callbacks attached with the same |nvim_buf_attach()| call. +callbacks attached with the same |nvim_buf_attach()| call without invoking the +"on_detach" callback. ============================================================================== @@ -2179,7 +2180,8 @@ nvim_create_autocmd({event}, {opts}) *nvim_create_autocmd()* Parameters: ~ • {event} (`vim.api.keyset.events|vim.api.keyset.events[]`) Event(s) - that will trigger the handler (`callback` or `command`). + that will trigger the handler (`callback` or `command`): one + handler is created for each event name. • {opts} (`vim.api.keyset.create_autocmd?`) Options dict: • buf (`integer?`) Buffer id for buffer-local autocommands |autocmd-buflocal|. Not allowed with {pattern}. @@ -2206,7 +2208,8 @@ nvim_create_autocmd({event}, {opts}) *nvim_create_autocmd()* • nested (`boolean?`, default: false) Run nested autocommands |autocmd-nested|. • once (`boolean?`, default: false) Handle the event only - once |autocmd-once|. + once |autocmd-once|. If {event} is a list, each handler + will fire once. • pattern (`string|array?`) Pattern(s) to match literally |autocmd-pattern|. @@ -2385,8 +2388,8 @@ nvim_buf_attach({buf}, {send_buffer}, {opts}) *nvim_buf_attach()* • {opts} (`vim.api.keyset.buf_attach?`) Optional parameters. • on_bytes: Called on granular changes (compared to on_lines). Not called on buffer reload (`:checktime`, - `:edit`, …), see `on_reload:`. Return a - |lua-truthy| value to detach. Args: + `:edit`, …), see `on_reload`. Returning + |lua-truthy| deletes the callback. Args: • the string "bytes" • buffer id • b:changedtick @@ -2409,13 +2412,15 @@ nvim_buf_attach({buf}, {send_buffer}, {opts}) *nvim_buf_attach()* • the string "changedtick" • buffer id • b:changedtick - • on_detach: Called on detach. Args: + • on_detach: Called on detach, or when the buffer is + unloaded or deleted. Not called when a callback + returns |lua-truthy| to delete itself. Args: • the string "detach" • buffer id • on_lines: Called on linewise changes. Not called on buffer reload (`:checktime`, `:edit`, …), see - `on_reload:`. Return a |lua-truthy| value to detach. - Args: + `on_reload`. Returning |lua-truthy| deletes the + callback. Args: • the string "lines" • buffer id • b:changedtick diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index ab69a1ea97..adbe7e874e 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -55,7 +55,8 @@ Vimscript commands are described below. they execute in the order in which they were defined. See |autocmd-nested| for [++nested]. *autocmd-once* - If [++once] is supplied the command is executed once, + If [++once] is supplied the command is executed once + (per {event}, which may be a comma-separated list), then removed ("one shot"). The special pattern or defines a buffer-local autocommand. diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt index a95437ba24..3c5b4938e8 100644 --- a/runtime/doc/cmdline.txt +++ b/runtime/doc/cmdline.txt @@ -1189,7 +1189,7 @@ Also see |`=|. 7. Command-line window *cmdline-window* *cmdwin* *command-line-window* The command-line window ("cmdwin") is a buffer+window in which the command -line can be edited. +line can be edited. See also |:exmode|, a REPL-like mode based on the cmdwin. OPEN *c_CTRL-F* *q:* *q/* *q?* diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index b2d89c8162..0796f1306b 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -6105,7 +6105,7 @@ To enable this feature (default opts shown): >lua msg = { -- Options related to the message module. ---@type string|table Default message target ---or table mapping |ui-messages| kinds, triggers and IDs to a target. - ---Table keys are are matched as a Lua pattern to the message ID. 'default' + ---Table keys are matched as a Lua pattern to the message ID. 'default' ---mapping applies to any omitted kind: { default = 'cmd', progress = 'msg' }. targets = 'cmd', cmd = { -- Options related to messages in the cmdline window. diff --git a/runtime/doc/plugins.txt b/runtime/doc/plugins.txt index c2415ca796..9f10625251 100644 --- a/runtime/doc/plugins.txt +++ b/runtime/doc/plugins.txt @@ -100,28 +100,28 @@ entry name: |dir-buffer-mappings| resolve the line under the cursor against the buffer name, so rewriting line text makes open a nonexistent path. Sort directories last: >vim - autocmd User DirReadPost silent keeppatterns sort r /\/$/ + autocmd User DirReadPost silent keeppatterns sort r /\/$/ < Hide dot-prefixed entries: >vim - autocmd User DirReadPost silent keeppatterns g/^\./d _ + autocmd User DirReadPost silent keeppatterns g/^\./d _ < Sort by modification time, newest first: >lua - vim.api.nvim_create_autocmd('User', { - pattern = 'DirReadPost', - callback = function(args) - local dir = vim.api.nvim_buf_get_name(args.buf) - local names = vim.api.nvim_buf_get_lines(args.buf, 0, -1, true) - local mtime = {} --- @type table - for _, name in ipairs(names) do - local stat = vim.uv.fs_stat(vim.fs.joinpath(dir, name)) - mtime[name] = stat and stat.mtime.sec or 0 - end - table.sort(names, function(a, b) - return mtime[a] > mtime[b] - end) - vim.api.nvim_buf_set_lines(args.buf, 0, -1, true, names) - end, - }) + vim.api.nvim_create_autocmd('User', { + pattern = 'DirReadPost', + callback = function(args) + local dir = vim.api.nvim_buf_get_name(args.buf) + local names = vim.api.nvim_buf_get_lines(args.buf, 0, -1, true) + local mtime = {} --- @type table + for _, name in ipairs(names) do + local stat = vim.uv.fs_stat(vim.fs.joinpath(dir, name)) + mtime[name] = stat and stat.mtime.sec or 0 + end + table.sort(names, function(a, b) + return mtime[a] > mtime[b] + end) + vim.api.nvim_buf_set_lines(args.buf, 0, -1, true, names) + end, + }) < Decorating the listing *dir-decorate* @@ -130,40 +130,40 @@ A |nvim_set_decoration_provider()| sets |extmarks| on the visible lines of each redraw, so they survive reordering by a |DirReadPost| handler. Classify each entry, and show where a symbolic link points: >lua - local ns = vim.api.nvim_create_namespace('my.dir.classify') - local glyph = { - fifo = '|', socket = '=', char = '%', block = '#', - } - vim.api.nvim_set_decoration_provider(ns, { - on_win = function(_, _, buf) - return vim.bo[buf].filetype == 'directory' - end, - on_range = function(_, _, buf, row) - local dir = vim.api.nvim_buf_get_name(buf) - local name = vim.api.nvim_buf_get_lines(buf, row, row + 1, true)[1] - local path = vim.fs.joinpath(dir, (name:gsub('/$', ''))) - local stat = vim.uv.fs_lstat(path) or {} - local exe = stat.type == 'file' - and bit.band(stat.mode, tonumber('111', 8)) ~= 0 - local char = glyph[stat.type] or (exe and '*') - if char then - vim.api.nvim_buf_set_extmark(buf, ns, row, #name, { - virt_text = { { char, 'Dimmed' } }, - virt_text_pos = 'overlay', - ephemeral = true, - }) - end - if stat.type == 'link' then - local target = vim.uv.fs_readlink(path) or '?' - vim.api.nvim_buf_set_extmark(buf, ns, row, 0, { - virt_text = { { '-> ' .. target, 'Dimmed' } }, - virt_text_pos = 'eol', - ephemeral = true, - }) - end - return row + 1 - end, - }) + local ns = vim.api.nvim_create_namespace('my.dir.classify') + local glyph = { + fifo = '|', socket = '=', char = '%', block = '#', + } + vim.api.nvim_set_decoration_provider(ns, { + on_win = function(_, _, buf) + return vim.bo[buf].filetype == 'directory' + end, + on_range = function(_, _, buf, row) + local dir = vim.api.nvim_buf_get_name(buf) + local name = vim.api.nvim_buf_get_lines(buf, row, row + 1, true)[1] + local path = vim.fs.joinpath(dir, (name:gsub('/$', ''))) + local stat = vim.uv.fs_lstat(path) or {} + local exe = stat.type == 'file' + and bit.band(stat.mode, tonumber('111', 8)) ~= 0 + local char = glyph[stat.type] or (exe and '*') + if char then + vim.api.nvim_buf_set_extmark(buf, ns, row, #name, { + virt_text = { { char, 'Dimmed' } }, + virt_text_pos = 'overlay', + ephemeral = true, + }) + end + if stat.type == 'link' then + local target = vim.uv.fs_readlink(path) or '?' + vim.api.nvim_buf_set_extmark(buf, ns, row, 0, { + virt_text = { { '-> ' .. target, 'Dimmed' } }, + virt_text_pos = 'eol', + ephemeral = true, + }) + end + return row + 1 + end, + }) < Replacing the directory browser *dir-disable* diff --git a/runtime/doc/repeat.txt b/runtime/doc/repeat.txt index c87d218e62..c938c4d085 100644 --- a/runtime/doc/repeat.txt +++ b/runtime/doc/repeat.txt @@ -38,13 +38,12 @@ Repeating a Visual-mode command re-executes the captured keysequence, selection included. See |visual-repeat|. ============================================================================== -Semantic repeat *cmdatom* *action-repeat* +Semantic repeat *action-repeat* *cmdatom* *excalibur* The |CmdAtom| event is published on every user action. This avoids the need for plugins to "announce" the repeatable unit, thus plugins like vim-repeat aren't needed. - *excalibur* `CmdAtom.lhs` is the high-level user input collected during an action, including getchar() input. This is signficant: it reflects the semantic intent. `CmdAtom.keys` reveals the low-level internal commands that were diff --git a/runtime/lua/vim/_core/ui2.lua b/runtime/lua/vim/_core/ui2.lua index 29412de3b3..b1281ee85d 100644 --- a/runtime/lua/vim/_core/ui2.lua +++ b/runtime/lua/vim/_core/ui2.lua @@ -10,7 +10,7 @@ --- msg = { -- Options related to the message module. --- ---@type string|table Default message target --- ---or table mapping |ui-messages| kinds, triggers and IDs to a target. ---- ---Table keys are are matched as a Lua pattern to the message ID. 'default' +--- ---Table keys are matched as a Lua pattern to the message ID. 'default' --- ---mapping applies to any omitted kind: { default = 'cmd', progress = 'msg' }. --- targets = 'cmd', --- cmd = { -- Options related to messages in the cmdline window. diff --git a/runtime/lua/vim/_meta/api.gen.lua b/runtime/lua/vim/_meta/api.gen.lua index cd23a3a97c..2ccc0674e4 100644 --- a/runtime/lua/vim/_meta/api.gen.lua +++ b/runtime/lua/vim/_meta/api.gen.lua @@ -226,8 +226,8 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- Not for Lua callbacks. --- @param opts vim.api.keyset.buf_attach? Optional parameters. --- - on_bytes: Called on granular changes (compared to on_lines). Not called on buffer ---- reload (`:checktime`, `:edit`, …), see `on_reload:`. Return a [lua-truthy] value ---- to detach. Args: +--- reload (`:checktime`, `:edit`, …), see `on_reload`. Returning [lua-truthy] deletes +--- the callback. Args: --- - the string "bytes" --- - buffer id --- - b:changedtick @@ -247,11 +247,12 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- - the string "changedtick" --- - buffer id --- - b:changedtick ---- - on_detach: Called on detach. Args: +--- - on_detach: Called on detach, or when the buffer is unloaded or deleted. Not called +--- when a callback returns [lua-truthy] to delete itself. Args: --- - the string "detach" --- - buffer id --- - on_lines: Called on linewise changes. Not called on buffer reload (`:checktime`, ---- `:edit`, …), see `on_reload:`. Return a [lua-truthy] value to detach. Args: +--- `:edit`, …), see `on_reload`. Returning [lua-truthy] deletes the callback. Args: --- - the string "lines" --- - buffer id --- - b:changedtick @@ -954,7 +955,8 @@ function vim.api.nvim_create_augroup(name, opts) end --- --- @see `:help autocommand` --- @see vim.api.nvim_del_autocmd ---- @param event vim.api.keyset.events|vim.api.keyset.events[] Event(s) that will trigger the handler (`callback` or `command`). +--- @param event vim.api.keyset.events|vim.api.keyset.events[] Event(s) that will trigger the handler (`callback` or `command`): one handler is +--- created for each event name. --- @param opts vim.api.keyset.create_autocmd? Options dict: --- - buf (`integer?`) Buffer id for buffer-local autocommands `autocmd-buflocal`. --- Not allowed with {pattern}. @@ -972,7 +974,8 @@ function vim.api.nvim_create_augroup(name, opts) end --- - desc (`string?`) Description (for documentation and troubleshooting). --- - group (`string|integer?`) Group name or id to match against. --- - nested (`boolean?`, default: false) Run nested autocommands `autocmd-nested`. ---- - once (`boolean?`, default: false) Handle the event only once `autocmd-once`. +--- - once (`boolean?`, default: false) Handle the event only once `autocmd-once`. If {event} +--- is a list, each handler will fire once. --- - pattern (`string|array?`) Pattern(s) to match literally `autocmd-pattern`. --- @return integer # Autocommand id (number) function vim.api.nvim_create_autocmd(event, opts) end diff --git a/runtime/lua/vim/lsp/sync.lua b/runtime/lua/vim/lsp/sync.lua index 36a94d5fba..24a23183f8 100644 --- a/runtime/lua/vim/lsp/sync.lua +++ b/runtime/lua/vim/lsp/sync.lua @@ -401,7 +401,7 @@ function M.compute_diff( position_encoding ) -- Find the last position changed in the previous and current buffer. - -- prev_end_range is sent to the server as as the end of the changed range. + -- prev_end_range is sent to the server as the end of the changed range. -- curr_end_range is used to grab the changed text from the latest buffer. local prev_end_range, curr_end_range = compute_end_range( prev_lines, diff --git a/src/nvim/api/autocmd.c b/src/nvim/api/autocmd.c index 0bb2eeb796..f046ce72bd 100644 --- a/src/nvim/api/autocmd.c +++ b/src/nvim/api/autocmd.c @@ -365,7 +365,8 @@ cleanup: /// pattern = vim.fn.expand('~') .. '/some/path/*.py' /// ``` /// -/// @param event Event(s) that will trigger the handler (`callback` or `command`). +/// @param event Event(s) that will trigger the handler (`callback` or `command`): one handler is +/// created for each event name. /// @param opts Options dict: /// - buf (`integer?`) Buffer id for buffer-local autocommands |autocmd-buflocal|. /// Not allowed with {pattern}. @@ -383,7 +384,8 @@ cleanup: /// - desc (`string?`) Description (for documentation and troubleshooting). /// - group (`string|integer?`) Group name or id to match against. /// - nested (`boolean?`, default: false) Run nested autocommands |autocmd-nested|. -/// - once (`boolean?`, default: false) Handle the event only once |autocmd-once|. +/// - once (`boolean?`, default: false) Handle the event only once |autocmd-once|. If {event} +/// is a list, each handler will fire once. /// - pattern (`string|array?`) Pattern(s) to match literally |autocmd-pattern|. /// /// @return Autocommand id (number) diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c index 4ac3cc932c..6baee67ca1 100644 --- a/src/nvim/api/buffer.c +++ b/src/nvim/api/buffer.c @@ -127,8 +127,8 @@ Integer nvim_buf_line_count(Buffer buf, Error *err) /// Not for Lua callbacks. /// @param opts Optional parameters. /// - on_bytes: Called on granular changes (compared to on_lines). Not called on buffer -/// reload (`:checktime`, `:edit`, …), see `on_reload:`. Return a [lua-truthy] value -/// to detach. Args: +/// reload (`:checktime`, `:edit`, …), see `on_reload`. Returning [lua-truthy] deletes +/// the callback. Args: /// - the string "bytes" /// - buffer id /// - b:changedtick @@ -148,11 +148,12 @@ Integer nvim_buf_line_count(Buffer buf, Error *err) /// - the string "changedtick" /// - buffer id /// - b:changedtick -/// - on_detach: Called on detach. Args: +/// - on_detach: Called on detach, or when the buffer is unloaded or deleted. Not called +/// when a callback returns [lua-truthy] to delete itself. Args: /// - the string "detach" /// - buffer id /// - on_lines: Called on linewise changes. Not called on buffer reload (`:checktime`, -/// `:edit`, …), see `on_reload:`. Return a [lua-truthy] value to detach. Args: +/// `:edit`, …), see `on_reload`. Returning [lua-truthy] deletes the callback. Args: /// - the string "lines" /// - buffer id /// - b:changedtick diff --git a/src/nvim/eval/typval.c b/src/nvim/eval/typval.c index 72d293c8cd..541c59ba63 100644 --- a/src/nvim/eval/typval.c +++ b/src/nvim/eval/typval.c @@ -2026,7 +2026,7 @@ bool tv_dict_watcher_remove(dict_T *const dict, const char *const key_pattern, return true; } -/// Test if `key` matches with with `watcher->key_pattern` +/// Test if `key` matches with `watcher->key_pattern` /// /// @param[in] watcher Watcher to check key pattern from. /// @param[in] key Key to check. diff --git a/src/nvim/eval/typval.h b/src/nvim/eval/typval.h index db88629858..c266a42a6f 100644 --- a/src/nvim/eval/typval.h +++ b/src/nvim/eval/typval.h @@ -268,7 +268,7 @@ static inline uint8_t tv_blob_get(const blob_T *const b, int idx) /// Store the byte `c` at index `idx` in the blob. /// -/// @param[in] b Blob to index. Cannot be NULL. +/// @param[in] blob Blob to index. Cannot be NULL. /// @param[in] idx Index in a blob. Must be valid. /// @param[in] c Value to store. static inline void tv_blob_set(blob_T *const blob, int idx, uint8_t c) diff --git a/src/nvim/lua/converter.c b/src/nvim/lua/converter.c index d9a4e0a0c9..222c7f1439 100644 --- a/src/nvim/lua/converter.c +++ b/src/nvim/lua/converter.c @@ -975,7 +975,7 @@ Array nlua_pop_Array(lua_State *lstate, Arena *arena, Error *err) /// Convert Lua table to dictionary /// -/// Always pops one value from the stack. Does not check whether whether topmost +/// Always pops one value from the stack. Does not check whether topmost /// value on the stack is a table. /// /// @param lstate Lua interpreter state. diff --git a/src/nvim/marktree.c b/src/nvim/marktree.c index 9eb0c5562b..a44a1ad70a 100644 --- a/src/nvim/marktree.c +++ b/src/nvim/marktree.c @@ -39,7 +39,7 @@ // OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF // SUCH DAMAGE. // -// Changes done by by the neovim project follow the Apache v2 license available +// Changes done by the neovim project follow the Apache v2 license available // at the repo root. #include diff --git a/src/nvim/option.c b/src/nvim/option.c index c918a14171..ecf2609464 100644 --- a/src/nvim/option.c +++ b/src/nvim/option.c @@ -2396,7 +2396,7 @@ static const char *did_set_laststatus(optset_T *args) clear_cmdline = true; } // When switching from global statusline, increase height of topframe by STATUS_HEIGHT - // in order to to re-add the space that was previously taken by the global statusline + // in order to re-add the space that was previously taken by the global statusline if (old_value == 3 && value != 3) { frame_new_height(topframe, topframe->fr_height + STATUS_HEIGHT, false, false, false); win_comp_pos(); diff --git a/src/nvim/register.c b/src/nvim/register.c index ac6a766987..eec04da895 100644 --- a/src/nvim/register.c +++ b/src/nvim/register.c @@ -163,7 +163,7 @@ bool valid_yank_reg(int regname, bool writing) /// clipboard register. This happens when `clipboard=unnamed[plus]` is set /// and a provider is available. /// -/// @returns the name of of a clipboard register that should be used, or `NUL` if none. +/// @returns the name of a clipboard register that should be used, or `NUL` if none. int get_default_register_name(void) { int name = NUL; diff --git a/src/nvim/runtime.c b/src/nvim/runtime.c index 4936c37558..33d97e5054 100644 --- a/src/nvim/runtime.c +++ b/src/nvim/runtime.c @@ -823,7 +823,7 @@ static bool path_is_after(char *buf, size_t buflen) { // NOTE: we only consider dirs exactly matching "after" to be an AFTER dir. // vim8 considers all dirs like "foo/bar_after", "Xafter" etc, as an - // "after" dir in SOME codepaths not not in ALL codepaths. + // "after" dir in SOME codepaths not in ALL codepaths. return buflen >= 5 && (!(buflen >= 6) || vim_ispathsep(buf[buflen - 6])) && strcmp(buf + buflen - 5, "after") == 0;