docs: misc #39243

10 files changed, 65 insertions, 15 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 75c7c1f2e9..6555565b66 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 dac2831ecb..c9e81cd9b3 100644
--- a/runtime/doc/dev_arch.txt
+++ b/runtime/doc/dev_arch.txt
@@ -125,8 +125,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*
@@ -186,6 +185,44 @@ be "fast". For example, commit 3940c435e405 fixed such a bug with
 Common examples of non-fast code: regexp matching, wildcard expansion,
 expression evaluation.
 
+==============================================================================
+Internal practices and patterns                          *dev-internals-howto*
+
+------------------------------------------------------------------------------
+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):
+
+1. Full Lua: the implementation lives in entirely in Lua. This has
+   a performance benefit: the Vimscript <=> Lua bridge is skipped when the
+   `vim.fn.xx()` function is called from Lua. Examples:
+    - `f_hostname`
+2. Partial Lua: the C implementation calls `nlua_call_vimfn` or
+   `nlua_call_excmd`. (Or in rare cases: `nlua_exec` / `NLUA_EXEC_STATIC`).
+   Examples:
+   - `ex_log`
+   - `ex_lsp`
+   - `f_serverlist`
+3. Legacy way: implement the function entirely in C.
+   Examples:
+   - `f_chansend`
+   - `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 8b6ed4260f..8ac9f3090f 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -5726,8 +5726,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 74221e9a04..fb9f5415eb 100644
--- a/runtime/lua/vim/_meta/options.gen.lua
+++ b/runtime/lua/vim/_meta/options.gen.lua
@@ -6007,8 +6007,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 067b669f7e..3d2fb1f566 100644
--- a/runtime/lua/vim/diagnostic.lua
+++ b/runtime/lua/vim/diagnostic.lua
@@ -73,7 +73,8 @@ end
 --- - `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<string,boolean>
   --- 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 74746f201e..7821179c76 100644
--- a/src/nvim/options.lua
+++ b/src/nvim/options.lua
@@ -7910,8 +7910,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*