docs: misc #39207

3 files changed, 27 insertions, 8 deletions

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*