From 2b52acfb8a6c43db0e31abe8975330ea3363bd5d Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Mon, 20 Apr 2026 07:09:37 -0400 Subject: [PATCH] docs: misc #39207 --- .github/scripts/labeler_configuration.yml | 4 ++++ .github/workflows/labeler_issue.yml | 2 +- runtime/doc/dev_arch.txt | 19 ++++++++++++++++--- runtime/doc/diagnostic.txt | 11 ++++++++--- runtime/doc/options.txt | 5 +++-- runtime/lua/vim/_meta/options.gen.lua | 5 +++-- runtime/lua/vim/diagnostic.lua | 3 ++- src/nvim/auevents.lua | 2 +- src/nvim/memfile.c | 2 +- src/nvim/options.lua | 5 +++-- 10 files changed, 42 insertions(+), 16 deletions(-) diff --git a/.github/scripts/labeler_configuration.yml b/.github/scripts/labeler_configuration.yml index eea63a41eb..933e0bcbbd 100644 --- a/.github/scripts/labeler_configuration.yml +++ b/.github/scripts/labeler_configuration.yml @@ -86,6 +86,10 @@ tui: - changed-files: - any-glob-to-any-file: [ src/nvim/tui/tui.* ] +ui2: + - changed-files: + - any-glob-to-any-file: [ "runtime/lua/vim/_core/ui2*" ] + ux-visibility: - changed-files: - any-glob-to-any-file: [ "**/health.lua" ] diff --git a/.github/workflows/labeler_issue.yml b/.github/workflows/labeler_issue.yml index ea12181148..1b83b2ed26 100644 --- a/.github/workflows/labeler_issue.yml +++ b/.github/workflows/labeler_issue.yml @@ -17,7 +17,7 @@ jobs: script: | const title = context.payload.issue.title; const titleSplit = title.split(/\b/).map(e => e.toLowerCase()); - const keywords = ['api', 'treesitter', 'ui', 'lsp']; + const keywords = ['api', 'treesitter', 'ui', 'ui2', 'lsp']; var match = new Set(); for (const keyword of keywords) { if (titleSplit.includes(keyword)) { diff --git a/runtime/doc/dev_arch.txt b/runtime/doc/dev_arch.txt index a7c4e613b0..e94cbcd450 100644 --- a/runtime/doc/dev_arch.txt +++ b/runtime/doc/dev_arch.txt @@ -131,8 +131,7 @@ internal |event-loop|.) Where possible, new editor events should be implemented using `aucmd_defer()` (and where possible, old events migrate to this), so they are processed in -a predictable manner, which avoids crashes and race conditions. See -`do_markset_autocmd` for an example. +a predictable manner, which avoids crashes. See |dev-new-event|. ============================================================================== UI events *dev-ui-events* @@ -196,7 +195,7 @@ expression evaluation. Internal practices and patterns *dev-internals-howto* ------------------------------------------------------------------------------ -How to add a new Ex cmd or "vimfn" function ("f_xx"/"builtin"/"eval") +Add a new excmd or vimfn ("f_xx") function *dev-new-excmd* *dev-new-vimfn* To implement an Ex cmd or f_xx function, choose from one of three ways (in order of preference): @@ -217,6 +216,20 @@ order of preference): - `f_flatten` - `f_searchpos` +------------------------------------------------------------------------------ +Add a new event (autocmd) *dev-new-event* + +To add a new editor event (autocmd): + +1. Register the event name in `src/nvim/auevents.lua`. If the event is + Nvim-only (not in Vim), also update the `nvim_specific` table. +2. Fire the event, by one of these approaches: + - From C, use `aucmd_defer()` to fire deferred (safe, predictable). See + `do_markset_autocmd` for example. + - From Lua, use `vim.api.nvim_exec_autocmds()`. +3. Define the |event-data| type (if any) in `runtime/lua/vim/_meta/events.lua`. +4. Document the event in `runtime/doc/autocmd.txt`. + ============================================================================== The event-loop *event-loop* diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt index 80d4ae77b4..7fb406da25 100644 --- a/runtime/doc/diagnostic.txt +++ b/runtime/doc/diagnostic.txt @@ -380,11 +380,13 @@ DiagnosticSignOk *hl-DiagnosticDeprecated* DiagnosticDeprecated - Used for deprecated or obsolete code. + Used for deprecated or obsolete code. Applied by the "underline" handler; + disabled when `vim.diagnostic.config({ underline = false })`. *hl-DiagnosticUnnecessary* DiagnosticUnnecessary - Used for unnecessary or unused code. + Used for unnecessary or unused code. Applied by the "underline" handler; + disabled when `vim.diagnostic.config({ underline = false })`. ============================================================================== SIGNS *diagnostic-signs* @@ -536,7 +538,10 @@ Lua module: vim.diagnostic *diagnostic-api* Fields: ~ • {underline}? (`boolean|vim.diagnostic.Opts.Underline|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Underline`, default: `true`) - Use underline for diagnostics. + Used to call attention to a diagnostic + ("underline" is a misnomer). Controls the + |hl-DiagnosticUnnecessary| and + |hl-DiagnosticDeprecated| highlights. • {virtual_text}? (`boolean|vim.diagnostic.Opts.VirtualText|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.VirtualText`, default: `false`) Use virtual text for diagnostics. If multiple diagnostics are set for a namespace, one prefix diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index de92fc98ff..f7a796c24d 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -5738,8 +5738,9 @@ A jump table for the options with a short description can be found at |Q_op|. *'shortmess'* *'shm'* *E1336* 'shortmess' 'shm' string (default "ltToOCF") global - This option helps to avoid all the |hit-enter| prompts caused by file - messages, for example with CTRL-G, and to avoid some other messages. + Controls display of file messages (e.g. CTRL-G) and various other + messages. + It is a list of flags: flag meaning when present ~ l use "999L, 888B" instead of "999 lines, 888 bytes" *shm-l* diff --git a/runtime/lua/vim/_meta/options.gen.lua b/runtime/lua/vim/_meta/options.gen.lua index 82f53eedc7..3842c9a56d 100644 --- a/runtime/lua/vim/_meta/options.gen.lua +++ b/runtime/lua/vim/_meta/options.gen.lua @@ -6018,8 +6018,9 @@ vim.o.sw = vim.o.shiftwidth vim.bo.shiftwidth = vim.o.shiftwidth vim.bo.sw = vim.bo.shiftwidth ---- This option helps to avoid all the `hit-enter` prompts caused by file ---- messages, for example with CTRL-G, and to avoid some other messages. +--- Controls display of file messages (e.g. CTRL-G) and various other +--- messages. +--- --- It is a list of flags: --- flag meaning when present ~ --- l use "999L, 888B" instead of "999 lines, 888 bytes" *shm-l* diff --git a/runtime/lua/vim/diagnostic.lua b/runtime/lua/vim/diagnostic.lua index 8431d35953..b0c5fdc05c 100644 --- a/runtime/lua/vim/diagnostic.lua +++ b/runtime/lua/vim/diagnostic.lua @@ -69,7 +69,8 @@ local M = vim._defer_require('vim.diagnostic', { --- - `function`: Function with signature (namespace, bufnr) that returns any of the above. --- @class vim.diagnostic.Opts --- ---- Use underline for diagnostics. +--- Used to call attention to a diagnostic ("underline" is a misnomer). +--- Controls the |hl-DiagnosticUnnecessary| and |hl-DiagnosticDeprecated| highlights. --- (default: `true`) --- @field underline? boolean|vim.diagnostic.Opts.Underline|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Underline --- diff --git a/src/nvim/auevents.lua b/src/nvim/auevents.lua index f3e26720e1..4463f0c291 100644 --- a/src/nvim/auevents.lua +++ b/src/nvim/auevents.lua @@ -1,7 +1,7 @@ return { --- @type table --- Keys are events names. - --- Values are boolean indicating whether the event is window-local. + --- Value is true if the event is window-local, else false. events = { BufAdd = true, -- after adding a buffer to the buffer list BufDelete = true, -- deleting a buffer from the buffer list diff --git a/src/nvim/memfile.c b/src/nvim/memfile.c index 4bf26a8059..6e9a63a7f1 100644 --- a/src/nvim/memfile.c +++ b/src/nvim/memfile.c @@ -318,7 +318,7 @@ bhdr_T *mf_get(memfile_T *mfp, blocknr_T nr, unsigned page_count) } hp->bh_flags |= BH_LOCKED; - pmap_put(int64_t)(&mfp->mf_hash, hp->bh_bnum, hp); // put in front of hash table + pmap_put(int64_t)(&mfp->mf_hash, hp->bh_bnum, hp); return hp; } diff --git a/src/nvim/options.lua b/src/nvim/options.lua index a24da96883..cb3db201bd 100644 --- a/src/nvim/options.lua +++ b/src/nvim/options.lua @@ -7922,8 +7922,9 @@ local options = { cb = 'did_set_shortmess', defaults = 'ltToOCF', desc = [=[ - This option helps to avoid all the |hit-enter| prompts caused by file - messages, for example with CTRL-G, and to avoid some other messages. + Controls display of file messages (e.g. CTRL-G) and various other + messages. + It is a list of flags: flag meaning when present ~ l use "999L, 888B" instead of "999 lines, 888 bytes" *shm-l*