Merge #35462 from justinmk/doc2

runtime/doc/api-ui-events.txt

@@ -826,7 +826,8 @@ message window. Cmdline state is emitted as |ui-cmdline| events, which the UI
 must handle.
 
 ["msg_show", kind, content, replace_last, history, append, msg_id] ~
-	Display a message to the user.
+	Display a message to the user. Update (replace) any existing message
+	matching `msg_id`.
 
 	kind
 	    Name indicating the message kind:

runtime/doc/api.txt

@@ -254,19 +254,6 @@ The idea is "versionless evolution", in the words of Rich Hickey:
 - Relaxing a requirement should be a compatible change.
 - Strengthening a promise should be a compatible change.
 
-==============================================================================
-Global events                                               *api-global-events*
-
-When a client invokes an API request as an async notification, it is not
-possible for Nvim to send an error response. Instead, in case of error, the
-following notification will be sent to the client:
-
-                                                             *nvim_error_event*
-nvim_error_event[{type}, {message}]
-
-{type} is a numeric id as defined by `api_info().error_types`, and {message} is
-a string with the error message.
-
 ==============================================================================
 Buffer update events                                    *api-buffer-updates*
 
@@ -553,6 +540,38 @@ Extmark positions changed by an edit will be restored on undo/redo. Creating
 and deleting extmarks is not a buffer change, thus new undo states are not
 created for extmark changes.
 
+==============================================================================
+Global Events                                                     *api-events*
+
+nvim_error_event({type}, {msg})                             *nvim_error_event*
+    Emitted on the client channel if an async API request responds with an
+    error.
+
+    Attributes: ~
+        |RPC| only
+
+    Parameters: ~
+      • {type}  (`integer`) Error type id as defined by
+                `api_info().error_types`.
+      • {msg}   (`string`) Error message.
+
+nvim_ui_term_event({event}, {value})                      *nvim_ui_term_event*
+    Emitted by the TUI client to signal when a host-terminal event occurred.
+
+    Supports these events:
+    • "termresponse": The host-terminal sent a DA1, OSC, DCS, or APC response
+      sequence to Nvim. The payload is the received response. Sets
+      |v:termresponse| and fires |TermResponse|.
+
+    Attributes: ~
+        |RPC| only
+        Since: 0.10.0
+
+    Parameters: ~
+      • {event}  (`string`) Event name
+      • {value}  (`any`) Event payload
+
+
 ==============================================================================
 Global Functions                                                  *api-global*
 
@@ -1385,9 +1404,9 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes})
     debugging and orchestration. (Note: Something is better than nothing!
     Fields are optional, but at least set `name`.)
 
-    Can be called more than once; the caller should merge old info if
+    Can be called more than once; caller should merge old info if appropriate.
-    appropriate. Example: library first identifies the channel, then a plugin
+    Example: a library first identifies the channel, then a plugin using that
-    using that library later identifies itself.
+    library later identifies itself.
 
     Attributes: ~
         |RPC| only
@@ -3324,8 +3343,7 @@ nvim_set_decoration_provider({ns_id}, {opts})
                  • on_win: called when starting to redraw a specific window. >
                     ["win", winid, bufnr, toprow, botrow]
 <
-                 • on_line: called for each buffer line being redrawn. (The
+                 • on_line: (deprecated, use on_range instead) >
-                   interaction with fold lines is subject to change) >
                     ["line", winid, bufnr, row]
 <
                  • on_range: called for each buffer range being redrawn. Range
@@ -3661,22 +3679,6 @@ nvim_ui_set_option({name}, {value})                     *nvim_ui_set_option()*
       • {name}   (`string`)
       • {value}  (`any`)
 
-nvim_ui_term_event({event}, {value})                    *nvim_ui_term_event()*
-    Tells Nvim when a host-terminal event occurred.
-
-    Supports these events:
-    • "termresponse": The host-terminal sent a DA1, OSC, DCS, or APC response
-      sequence to Nvim. The payload is the received response. Sets
-      |v:termresponse| and fires |TermResponse|.
-
-    Attributes: ~
-        |RPC| only
-        Since: 0.10.0
-
-    Parameters: ~
-      • {event}  (`string`) Event name
-      • {value}  (`any`) Event payload
-
 nvim_ui_try_resize({width}, {height})                   *nvim_ui_try_resize()*
 
     Attributes: ~

runtime/doc/change.txt

@@ -1153,23 +1153,23 @@ first word).  You can use the |']| or |`]| command after the put command to
 move the cursor to the end of the inserted text, or use |'[| or |`[| to move
 the cursor to the start.
 
-						*put-Visual-mode* *v_p* *v_P*
+							     *put-Visual-mode*
 When using a put command like |p| or |P| in Visual mode, Vim will try to
-replace the selected text with the contents of the register.  Whether this
+replace the selected text with the contents of the register.  How this
-works well depends on the type of selection and the type of the text in the
+works depends on the type of selection and the text. With blockwise selection
-register.  With blockwise selection it also depends on the size of the block
+it also depends on the size of the block and whether the corners are on an
-and whether the corners are on an existing character.  (Implementation detail:
+existing character.  (Implementation detail: it actually works by first
-it actually works by first putting the register after the selection and then
+putting the register after the selection and then deleting the selection.)
-deleting the selection.)
+									 *v_p*
-With |p| the previously selected text is put in the unnamed register (and
+|p| in Visual mode puts text and sets the default register (unnamed,
-possibly the selection and/or clipboard).  This is useful if you want to put
+selection, or clipboard) to the previously-selected text.  Useful if you want
-that text somewhere else.  But you cannot repeat the same change.
+to put that text somewhere else.  But you cannot repeat the same change.
-With |P| the unnamed register is not changed (and neither the selection or
+									 *v_P*
-clipboard), you can repeat the same change. But the deleted text cannot be
+|P| in Visual mode puts text without setting the default register. You can
-used.  If you do need it you can use |p| with another register.  E.g., yank
+repeat the change, but the deleted text cannot be used.  If you do need it you
-the text to copy, Visually select the text to replace and use "0p .  You can
+can use |p| with another register.  E.g., yank the text to copy, Visually
-repeat this as many times as you like, and the unnamed register will be
+select the text to replace and use "0p .  You can repeat this as many times as
-changed each time.
+you like, and the unnamed register will be changed each time.
 							*blockwise-put*
 When a register contains text from one line (characterwise), using a
 blockwise Visual selection, putting that register will paste that text

runtime/doc/develop.txt

@@ -451,6 +451,8 @@ Use existing common {verb} names (actions) if possible:
                     a handler. |dev-name-events|
     - open:         Opens something (a buffer, window, …)
     - parse:        Parses something into a structured form
+    - request:      Calls a remote (network, RPC) operation.
+    - send:         Writes data or a message to a channel.
     - set:          Sets a thing (or group of things)
     - start:        Spin up a long-lived process. Prefer "enable" except when
                     "start" is obviously more appropriate.
@@ -461,7 +463,7 @@ Do NOT use these deprecated verbs:
     - contains:     Prefer "has".
     - disable:      Prefer `enable(enable: boolean)`.
     - exit:         Prefer "cancel" (or "stop" if appropriate).
-    - is_disabled:  Prefer `is_enabled()`.
+    - is_disabled:  Prefer `!is_enabled()`.
     - list:         Redundant with "get"
     - notify:       Redundant with "print", "echo"
     - show:         Redundant with "print", "echo"

runtime/doc/insert.txt

@@ -104,14 +104,13 @@ CTRL-R {register}				*i_CTRL-R*
 		Insert the contents of a register. Between typing CTRL-R and
 		the second character, '"' will be displayed to indicate that
 		you are expected to enter the name of a register. When used
-		with When used with named or clipboard registers
+		with named or clipboard registers (A-Z,a-z,0-9,+) text is
-		(A-Z,a-z,0-9,+) text is inserted literally like pasting with
+		inserted literally like pasting with "p". For other registers,
-		"p". For other registers, the text is inserted as if you typed
+		the text is inserted as if you typed it, but mappings and
-		it, but mappings and abbreviations are not used.  If you have
+		abbreviations are not used.  If you have options like
-		options like 'textwidth', 'formatoptions', or 'autoindent'
+		'textwidth', 'formatoptions', or 'autoindent' set, this will
-		set, this will influence what will be inserted. This is
+		influence what will be inserted. This is different from what
-		different from what happens with the "p" command and pasting
+		happens with the "p" command and pasting with the mouse.
-		with the mouse.
 		Special registers:
 			'"'	the unnamed register, containing the text of
 				the last delete or yank

runtime/doc/lsp.txt

@@ -2229,6 +2229,37 @@ is_enabled({filter})                         *vim.lsp.inlay_hint.is_enabled()*
 ==============================================================================
 Lua module: vim.lsp.inline_completion                  *lsp-inline_completion*
 
+This module provides the LSP "inline completion" feature, for completing
+multiline text (e.g., whole methods) instead of just a word or line, which may
+result in "syntactically or semantically incorrect" code. Unlike regular
+completion, this is typically presented as overlay text instead of a menu of
+completion candidates.
+
+LSP spec:
+https://microsoft.github.io/language-server-protocol/specifications/lsp/3.18/specification/#textDocument_inlineCompletion
+
+To try it out, here is a quickstart example using Copilot:       *lsp-copilot*
+1. Install Copilot: >sh
+    npm install --global @github/copilot-language-server
+<
+2. Define a config, (or copy `lsp/copilot.lua` from
+   https://github.com/neovim/nvim-lspconfig): >lua
+    vim.lsp.config('copilot', {
+     cmd = { 'copilot-language-server', '--stdio', },
+     root_markers = { '.git' },
+   })
+<
+3. Activate the config: >lua
+    vim.lsp.enable('copilot')
+<
+4. Sign in to Copilot, or use the `:LspCopilotSignIn` command from
+   https://github.com/neovim/nvim-lspconfig
+5. Enable inline completion: >lua
+    vim.lsp.inline_completion.enable()
+<
+6. Set a keymap for `vim.lsp.inline_completion.get()` and invoke the keymap.
+
+
 *vim.lsp.inline_completion.Item*
 
     Fields: ~

runtime/doc/lua-guide.txt

@@ -10,9 +10,9 @@
 ==============================================================================
 Introduction                                                         *lua-guide*
 
-This guide introduces the basics of everyday usage of Lua to configure and
+This guide introduces the basics of everyday Lua usage for configuring and
-operate Nvim. It assumes some familiarity with the (non-Lua) basics of Nvim
+controlling Nvim. It assumes some familiarity with the (non-Lua) basics of
-(commands, options, mappings, autocommands), which are covered in the
+Nvim (commands, options, mappings, autocommands), which are covered in the
 |user-manual|.
 
 This is not a comprehensive encyclopedia of all available features. Think of

runtime/doc/lua-plugin.txt

@@ -10,7 +10,7 @@
 ==============================================================================
 Introduction                                                       *lua-plugin*
 
-This document provides guidance for developing Nvim (Lua) plugins:
+This document provides guidance for developing Nvim Lua plugins.
 
 See |lua-guide| for guidance on using Lua to configure and operate Nvim.
 See |luaref| and |lua-concepts| for details on the Lua programming language.
@@ -19,7 +19,7 @@ See |luaref| and |lua-concepts| for details on the Lua programming language.
 Creating your first plugin                                    *lua-plugin-new*
 
 Any Vimscript or Lua code file that lives in the right directory,
-automatically is a "plugin". There's no maniest or "registration" required.
+automatically is a "plugin". There's no manifest or "registration" step.
 
 You can try it right now:
 
@@ -35,7 +35,7 @@ You can try it right now:
 
 Besides `plugin/foo.lua`, which is always run at startup, you can define Lua
 modules in the `lua/` directory. Those modules aren't loaded until your
-`plugin/foo.lua`, the user, calls `require(…)`.
+`plugin/foo.lua`, or the user, calls `require(…)`.
 
 ==============================================================================
 Type safety                                            *lua-plugin-type-safety*
@@ -108,11 +108,11 @@ In your plugin:
 >lua
     vim.keymap.set('n', '<Plug>(SayHello)', function()
         print('Hello from normal mode')
-    end, { noremap = true })
+    end)
 
     vim.keymap.set('v', '<Plug>(SayHello)', function()
         print('Hello from visual mode')
-    end, { noremap = true })
+    end)
 <
 In the user's config:
 >lua
@@ -176,7 +176,9 @@ For example, instead of:
     local foo = require('foo')
     vim.api.nvim_create_user_command('MyCommand', function()
         foo.do_something()
-    end, { -- ... })
+    end, {
+      -- ...
+    })
 <
 which calls `require('foo')` as soon as the module is loaded, you can
 lazy-load it by moving the `require` into the command's implementation:
@@ -227,7 +229,7 @@ A plugin tailored to Rust development might have initialization in
     -- e.g. add a |<Plug>| mapping or create a command
     vim.keymap.set('n', '<Plug>(MyPluginBufferAction)', function()
         print('Hello')
-    end, { noremap = true, buffer = bufnr, })
+    end, { buffer = bufnr, })
 <
 ==============================================================================
 Configuration                                              *lua-plugin-config*
@@ -274,7 +276,7 @@ Versioning and releases                                *lua-plugin-versioning*
 Consider:
 
 - Use |vim.deprecate()| or a `---@deprecate` annotation when you need to
-  communicate a (future) breaking change or discourged practice.
+  communicate a (future) breaking change or discouraged practice.
 - Using SemVer https://semver.org/ tags and releases to properly communicate
   bug fixes, new features, and breaking changes.
 - Automating versioning and releases in CI.
@@ -299,7 +301,9 @@ VERSIONING TOOLS
 Documentation                                                 *lua-plugin-doc*
 
 Provide vimdoc (see |help-writing|), so that users can read your plugin's
-documentation in Nvim, by entering `:h {plugin}` in |command-mode|.
+documentation in Nvim, by entering `:h {plugin}` in |command-mode|. The
+help-tags (the right-aligned "search keywords" in the help documents) are
+regenerated using the |:helptags| command.
 
 DOCUMENTATION TOOLS
 

runtime/doc/message.txt

@@ -848,25 +848,32 @@ prompt.
 ==============================================================================
 4. PROGRESS MESSAGE                                    *progress-message*
 
-Nvim can emit progress-message, which are a special kind of |ui-messages|
+Plugins and core Nvim features can emit "progress" |ui-messages| to report the
-used to report the state of long-running tasks.
+state of long-running tasks.
 
-Progress messages are created or updated using |nvim_echo()| with `kind='progress'`
+Create or update a progress-message by calling |nvim_echo()| with
-and the related options. Each message has a unique `msg_id`. A subsequent
+`kind='progress'`. Each message has a unique message-id, returned by
-message with the same `msg_id` replaces the older one.
+`nvim_echo`. You can specify the id when calling `nvim_echo` to update an
+existing progress-message.
 
 Events: ~
     • msg_show |ui-messages| event is fired for ext-ui upon creation/update of a
     progress-message
     • Updating or creating a progress message also triggers the |Progress| autocommand.
 
-Example: >
+Example: >lua
-    local id = vim.api.nvim_echo({{'searching...'}}, true,
+    local progress = {
-          {kind='progress', status='running', percent=10, title="term"})
+      kind = 'progress',
-    vim.api.nvim_echo({{'searching'}}, true,
+      status = 'running',
-          {id=id, kind='progress', status='running', percent=50, title="term"})
+      percent = 10,
-    vim.api.nvim_echo({{'done'}}, true,
+      title = 'term',
-          {id=id, kind='progress', status='success', percent=100, title="term"})
+    }
+    progress.id = vim.api.nvim_echo({ { 'searching...' } }, true, progress)
+    progress.percent = 50
+    vim.api.nvim_echo({ { 'searching' } }, true, progress)
+    progress.status = 'success'
+    progress.percent = 100
+    vim.api.nvim_echo({ { 'done' } }, true, progress)
 <
 See also: |nvim_echo()| |ui-messages| |Progress|
 

runtime/doc/news.txt

@@ -68,8 +68,9 @@ DIAGNOSTICS
 
 EDITOR
 
-• |i_CTRL-R| inserts named registers (A-Z,a-z,0-9) literally like pasting instead of
+- |i_CTRL-R| inserts named/clipboard registers (A-Z,a-z,0-9+) literally, like
-  as typed. To get the old behavior you can use `<C-R>=@x`.
+  pasting instead of like user input. Improves performance, avoids broken
+  formatting. To get the old behavior you can use `<C-R>=@x`.
 
 EVENTS
 
@@ -203,9 +204,8 @@ EVENTS
 HIGHLIGHTS
 
 • |hl-DiffTextAdd| highlights added text within a changed line.
-• |hl-StderrMsg| |hl-StdoutMsg|
+• |hl-OkMsg| |hl-StderrMsg| |hl-StdoutMsg|
 • |hl-SnippetTabstopActive| highlights the currently active tabstop.
-• |hl-OkMsg| highlights success messages.
 
 LSP
 
@@ -244,6 +244,7 @@ LSP
 • |vim.lsp.buf.signature_help()| supports "noActiveParameterSupport".
 • Support for `textDocument/inlineCompletion` |lsp-inline_completion|
   https://microsoft.github.io/language-server-protocol/specifications/lsp/3.18/specification/#textDocument_inlineCompletion
+  See |lsp-inline_completion| for quickstart instructions.
 • Support for `textDocument/onTypeFormatting`: |lsp-on_type_formatting|
   https://microsoft.github.io/language-server-protocol/specification/#textDocument_onTypeFormatting
 
@@ -291,6 +292,7 @@ PERFORMANCE
   support for nested braces and follows LSP 3.17 specification with
   additional constraints for improved correctness and resistance to
   backtracking edge cases.
+- |i_CTRL-R| inserts named/clipboard registers literally, 10x speedup.
 
 PLUGINS
 

runtime/doc/syntax.txt

@@ -5264,9 +5264,11 @@ EndOfBuffer	Filler lines (~) after the last line in the buffer.
 							*hl-TermCursor*
 TermCursor	Cursor in a focused terminal.
 							*hl-OkMsg*
-OkMsg		Success messages on the command line.
+OkMsg		Success messages.
+							*hl-WarningMsg*
+WarningMsg	Warning messages.
 							*hl-ErrorMsg*
-ErrorMsg	Error messages on the command line.
+ErrorMsg	Error messages.
 							*hl-StderrMsg*
 StderrMsg	Messages in stderr from shell commands.
 							*hl-StdoutMsg*
@@ -5407,8 +5409,6 @@ Title		Titles for output from ":set all", ":autocmd" etc.
 Visual		Visual mode selection.
 							*hl-VisualNOS*
 VisualNOS	Visual mode selection when vim is "Not Owning the Selection".
-							*hl-WarningMsg*
-WarningMsg	Warning messages.
 							*hl-Whitespace*
 Whitespace	"nbsp", "space", "tab", "multispace", "lead" and "trail"
 		in 'listchars'.

runtime/doc/vim_diff.txt

@@ -316,8 +316,9 @@ Commands:
 Editor:
 - |prompt-buffer| supports multiline input/paste, undo/redo, and o/O normal
   commands.
-- |i_CTRL-R| inserts named registers (A-Z,a-z,0-9) literally like pasting instead of
+- |i_CTRL-R| inserts named/clipboard registers (A-Z,a-z,0-9+) literally, like
-  as typed. To get the old behavior you can use `<C-R>=@x`.
+  pasting instead of like user input. Improves performance, avoids broken
+  formatting. To get the old behavior you can use `<C-R>=@x`.
 
 Events (autocommands):
 - Fixed inconsistent behavior in execution of nested autocommands #23368

runtime/lua/vim/_meta/api.lua

@@ -2157,8 +2157,7 @@ function vim.api.nvim_set_current_win(window) end
 ---   ```
 ---     ["win", winid, bufnr, toprow, botrow]
 ---   ```
---- - on_line: called for each buffer line being redrawn.
+--- - on_line: (deprecated, use on_range instead)
----     (The interaction with fold lines is subject to change)
 ---   ```
 ---     ["line", winid, bufnr, row]
 ---   ```

runtime/lua/vim/lsp/inline_completion.lua

@@ -1,3 +1,35 @@
+--- @brief
+--- This module provides the LSP "inline completion" feature, for completing multiline text (e.g.,
+--- whole methods) instead of just a word or line, which may result in "syntactically or
+--- semantically incorrect" code. Unlike regular completion, this is typically presented as overlay
+--- text instead of a menu of completion candidates.
+---
+--- LSP spec: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.18/specification/#textDocument_inlineCompletion
+---
+--- To try it out, here is a quickstart example using Copilot: [lsp-copilot]()
+---
+--- 1. Install Copilot:
+---    ```sh
+---    npm install --global @github/copilot-language-server
+---    ```
+--- 2. Define a config, (or copy `lsp/copilot.lua` from https://github.com/neovim/nvim-lspconfig):
+---    ```lua
+---    vim.lsp.config('copilot', {
+---      cmd = { 'copilot-language-server', '--stdio', },
+---      root_markers = { '.git' },
+---    })
+---    ```
+--- 3. Activate the config:
+---    ```lua
+---    vim.lsp.enable('copilot')
+---    ```
+--- 4. Sign in to Copilot, or use the `:LspCopilotSignIn` command from https://github.com/neovim/nvim-lspconfig
+--- 5. Enable inline completion:
+---    ```lua
+---    vim.lsp.inline_completion.enable()
+---    ```
+--- 6. Set a keymap for `vim.lsp.inline_completion.get()` and invoke the keymap.
+
 local util = require('vim.lsp.util')
 local log = require('vim.lsp.log')
 local protocol = require('vim.lsp.protocol')

scripts/cliff.toml

@@ -4,8 +4,8 @@
 # changelog header
 header = """
 # Changelog\n
-For notable changes, see runtime/doc/news.txt (or `:help news` in Nvim).\n
+Following is a list of commits (fixes/features only) in this release.\n
-Following is a list of fixes/features commits.\n
+See `:help news` in Nvim for release notes.\n
 """
 # template for the changelog body
 # https://github.com/Keats/tera

scripts/release.sh

@@ -97,5 +97,5 @@ echo "
 Next steps:
     - Run tests/CI (version_spec.lua)!
     - Push the tag:
-        git push --follow-tags
+        git push v${__VERSION}
     - Update website: index.html"

src/gen/gen_api_dispatch.lua

@@ -395,6 +395,7 @@ output:write([[
 #include "nvim/api/buffer.h"
 #include "nvim/api/command.h"
 #include "nvim/api/deprecated.h"
+#include "nvim/api/events.h"
 #include "nvim/api/extmark.h"
 #include "nvim/api/options.h"
 #include "nvim/api/tabpage.h"

src/gen/gen_help_html.lua

@@ -73,6 +73,7 @@ local new_layout = {
   ['intro.txt'] = true,
   ['lua.txt'] = true,
   ['lua-guide.txt'] = true,
+  ['lua-plugin.txt'] = true,
   ['luaref.txt'] = true,
   ['news.txt'] = true,
   ['news-0.9.txt'] = true,

src/gen/gen_vimdoc.lua

@@ -1,5 +1,8 @@
 #!/usr/bin/env -S nvim -l
---- Generates Nvim :help docs from Lua/C docstrings
+--- Generates Nvim :help docs from Lua/C docstrings.
+---
+--- Usage:
+---     make doc
 ---
 --- The generated :help text for each function is formatted as follows:
 --- - Max width of 78 columns (`TEXT_WIDTH`).
@@ -106,6 +109,7 @@ local config = {
     filename = 'api.txt',
     section_order = {
       -- Sections at the top, in a specific order:
+      'events.c',
       'vim.c',
       'vimscript.c',
 
@@ -126,11 +130,22 @@ local config = {
       ['vim.c'] = 'Global',
     },
     section_fmt = function(name)
+      if name == 'Events' then
+        return 'Global Events'
+      end
+
       return name .. ' Functions'
     end,
     helptag_fmt = function(name)
       return fmt('api-%s', name:lower())
     end,
+    fn_helptag_fmt = function(fun)
+      local name = fun.name
+      if vim.endswith(name, '_event') then
+        return name
+      end
+      return fn_helptag_fmt_common(fun)
+    end,
   },
   lua = {
     filename = 'lua.txt',

src/nvim/README.md

@@ -409,13 +409,18 @@ name, etc.
 
 All the global variables are declared in `globals.h`.
 
-### The main loop
+### The main event-loop
 
 The main loop is implemented in state_enter. The basic idea is that Vim waits
 for the user to type a character and processes it until another character is
 needed.  Thus there are several places where Vim waits for a character to be
 typed.  The `vgetc()` function is used for this.  It also handles mapping.
 
+What we consider the "Nvim event loop" is actually a wrapper around `uv_run` to
+handle both the `fast_events` queue and possibly (a suitable subset of) deferred
+events. Therefore "raw" `vim.uv.run()` is often not enough to "yield" from Lua
+plugins; instead they can call `vim.wait(0)`.
+
 Updating the screen is mostly postponed until a command or a sequence of
 commands has finished.  The work is done by `update_screen()`, which calls
 `win_update()` for every window, which calls `win_line()` for every line.

src/nvim/api/events.c

@@ -0,0 +1,76 @@
+#include <assert.h>
+#include <inttypes.h>
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "klib/kvec.h"
+#include "nvim/api/events.h"
+#include "nvim/api/private/converter.h"
+#include "nvim/api/private/defs.h"
+#include "nvim/api/private/helpers.h"
+#include "nvim/api/private/validate.h"
+#include "nvim/api/ui.h"
+#include "nvim/assert_defs.h"
+#include "nvim/autocmd.h"
+#include "nvim/autocmd_defs.h"
+#include "nvim/channel.h"
+#include "nvim/channel_defs.h"
+#include "nvim/eval.h"
+#include "nvim/globals.h"
+#include "nvim/main.h"
+#include "nvim/map_defs.h"
+#include "nvim/memory.h"
+#include "nvim/memory_defs.h"
+#include "nvim/msgpack_rpc/channel.h"
+#include "nvim/msgpack_rpc/channel_defs.h"
+#include "nvim/msgpack_rpc/packer.h"
+#include "nvim/msgpack_rpc/packer_defs.h"
+#include "nvim/types_defs.h"
+#include "nvim/ui.h"
+
+/// Emitted on the client channel if an async API request responds with an error.
+///
+/// @param channel_id
+/// @param type Error type id as defined by `api_info().error_types`.
+/// @param msg Error message.
+void nvim_error_event(uint64_t channel_id, Integer type, String msg)
+  FUNC_API_REMOTE_ONLY
+{
+  // TODO(bfredl): consider printing message to user, as will be relevant
+  // if we fork nvim processes as async workers
+  ELOG("async error on channel %" PRId64 ": %s", channel_id, msg.size ? msg.data : "");
+}
+
+/// Emitted by the TUI client to signal when a host-terminal event occurred.
+///
+/// Supports these events:
+///
+///   - "termresponse": The host-terminal sent a DA1, OSC, DCS, or APC response sequence to Nvim.
+///                     The payload is the received response. Sets |v:termresponse| and fires
+///                     |TermResponse|.
+///
+/// @param channel_id
+/// @param event Event name
+/// @param value Event payload
+/// @param[out] err Error details, if any.
+void nvim_ui_term_event(uint64_t channel_id, String event, Object value, Error *err)
+  FUNC_API_SINCE(12) FUNC_API_REMOTE_ONLY
+{
+  if (strequal("termresponse", event.data)) {
+    if (value.type != kObjectTypeString) {
+      api_set_error(err, kErrorTypeValidation, "termresponse must be a string");
+      return;
+    }
+
+    const String termresponse = value.data.string;
+    set_vim_var_string(VV_TERMRESPONSE, termresponse.data, (ptrdiff_t)termresponse.size);
+
+    MAXSIZE_TEMP_DICT(data, 1);
+    PUT_C(data, "sequence", value);
+    apply_autocmds_group(EVENT_TERMRESPONSE, NULL, NULL, true, AUGROUP_ALL, NULL, NULL,
+                         &DICT_OBJ(data));
+  }
+}

src/nvim/api/events.h

@@ -0,0 +1,8 @@
+#pragma once
+
+#include <stdint.h>  // IWYU pragma: keep
+
+#include "nvim/api/keysets_defs.h"  // IWYU pragma: keep
+#include "nvim/api/private/defs.h"  // IWYU pragma: keep
+
+#include "api/events.h.generated.h"

src/nvim/api/extmark.c

@@ -1033,8 +1033,7 @@ void nvim_buf_clear_namespace(Buffer buffer, Integer ns_id, Integer line_start,
 ///               ```
 ///                 ["win", winid, bufnr, toprow, botrow]
 ///               ```
-///             - on_line: called for each buffer line being redrawn.
+///             - on_line: (deprecated, use on_range instead)
-///                 (The interaction with fold lines is subject to change)
 ///               ```
 ///                 ["line", winid, bufnr, row]
 ///               ```

src/nvim/api/ui.c

@@ -567,37 +567,6 @@ void nvim_ui_pum_set_bounds(uint64_t channel_id, Float width, Float height, Floa
   ui->pum_pos = true;
 }
 
-/// Tells Nvim when a host-terminal event occurred.
-///
-/// Supports these events:
-///
-///   - "termresponse": The host-terminal sent a DA1, OSC, DCS, or APC response sequence to Nvim.
-///                     The payload is the received response. Sets |v:termresponse| and fires
-///                     |TermResponse|.
-///
-/// @param channel_id
-/// @param event Event name
-/// @param value Event payload
-/// @param[out] err Error details, if any.
-void nvim_ui_term_event(uint64_t channel_id, String event, Object value, Error *err)
-  FUNC_API_SINCE(12) FUNC_API_REMOTE_ONLY
-{
-  if (strequal("termresponse", event.data)) {
-    if (value.type != kObjectTypeString) {
-      api_set_error(err, kErrorTypeValidation, "termresponse must be a string");
-      return;
-    }
-
-    const String termresponse = value.data.string;
-    set_vim_var_string(VV_TERMRESPONSE, termresponse.data, (ptrdiff_t)termresponse.size);
-
-    MAXSIZE_TEMP_DICT(data, 1);
-    PUT_C(data, "sequence", value);
-    apply_autocmds_group(EVENT_TERMRESPONSE, NULL, NULL, true, AUGROUP_ALL, NULL, NULL,
-                         &DICT_OBJ(data));
-  }
-}
-
 static void flush_event(RemoteUI *ui)
 {
   if (ui->cur_event) {

src/nvim/api/vim.c

@@ -1558,7 +1558,7 @@ ArrayOf(Object, 2) nvim_get_api_info(uint64_t channel_id, Arena *arena)
 /// orchestration. (Note: Something is better than nothing! Fields are optional, but at least set
 /// `name`.)
 ///
-/// Can be called more than once; the caller should merge old info if appropriate. Example: library
+/// Can be called more than once; caller should merge old info if appropriate. Example: a library
 /// first identifies the channel, then a plugin using that library later identifies itself.
 ///
 /// @param channel_id
@@ -2222,15 +2222,6 @@ DictAs(eval_statusline_ret) nvim_eval_statusline(String str, Dict(eval_statuslin
   return result;
 }
 
-/// @nodoc
-void nvim_error_event(uint64_t channel_id, Integer lvl, String data)
-  FUNC_API_REMOTE_ONLY
-{
-  // TODO(bfredl): consider printing message to user, as will be relevant
-  // if we fork nvim processes as async workers
-  ELOG("async error on channel %" PRId64 ": %s", channel_id, data.size ? data.data : "");
-}
-
 /// EXPERIMENTAL: this API may change in the future.
 ///
 /// Sets info for the completion item at the given index. If the info text was shown in a window,

src/nvim/highlight.h

@@ -17,6 +17,8 @@ EXTERN const char *hlf_names[] INIT( = {
   [HLF_TERM] = "TermCursor",
   [HLF_AT] = "NonText",
   [HLF_D] = "Directory",
+  [HLF_OK] = "OkMsg",
+  [HLF_W] = "WarningMsg",
   [HLF_E] = "ErrorMsg",
   [HLF_SE] = "StderrMsg",
   [HLF_SO] = "StdoutMsg",
@@ -39,7 +41,6 @@ EXTERN const char *hlf_names[] INIT( = {
   [HLF_V] = "Visual",
   [HLF_VNC] = "VisualNC",
   [HLF_VSP] = "VertSplit",
-  [HLF_W] = "WarningMsg",
   [HLF_WM] = "WildMenu",
   [HLF_FL] = "Folded",
   [HLF_FC] = "FoldColumn",
@@ -84,7 +85,6 @@ EXTERN const char *hlf_names[] INIT( = {
   [HLF_BFOOTER] = "FloatFooter",
   [HLF_TS] = "StatusLineTerm",
   [HLF_TSNC] = "StatusLineTermNC",
-  [HLF_OK] = "OkMsg",
 });
 
 EXTERN int highlight_attr[HLF_COUNT];     // Highl. attr for each context.

src/nvim/message.c

@@ -344,7 +344,7 @@ static HlMessage format_progress_message(HlMessage hl_msg, MessageData *msg_data
 /// @param kind Message kind (can be NULL to avoid setting kind)
 /// @param history Whether to add message to history
 /// @param err Whether to print message as an error
-/// @param msg_data Additional data for progress messages
+/// @param msg_data Progress-message data
 MsgID msg_multihl(MsgID id, HlMessage hl_msg, const char *kind, bool history, bool err,
                   MessageData *msg_data, bool *needs_msg_clear)
 {

test/functional/editor/mode_insert_spec.lua

@@ -84,7 +84,7 @@ describe('insert-mode', function()
       ]])
     end)
 
-    it('inserts named registers literally', function()
+    it('inserts named/clipboard registers literally', function()
       local screen = Screen.new(50, 6)
       -- regular text without special charecter command
       command('let @a = "test"')

test/functional/lua/luaeval_spec.lua

@@ -93,7 +93,7 @@ describe('luaeval()', function()
   -- Not checked: funcrefs converted to NIL. To be altered to something more
   -- meaningful later.
 
-  it('correctly evaluates scalars', function()
+  it('scalars', function()
     -- Also test method call (->) syntax
     eq(1, fn.luaeval('1'))
     eq(0, eval('"1"->luaeval()->type()'))
@@ -114,7 +114,7 @@ describe('luaeval()', function()
     eq(NIL, fn.luaeval('nil'))
   end)
 
-  it('correctly evaluates containers', function()
+  it('containers', function()
     eq({}, fn.luaeval('{}'))
     eq(3, eval('type(luaeval("{}"))'))
 
@@ -145,7 +145,7 @@ describe('luaeval()', function()
     )
   end)
 
-  it('correctly passes scalars as argument', function()
+  it('passes scalars as argument', function()
     eq(1, fn.luaeval('_A', 1))
     eq(1.5, fn.luaeval('_A', 1.5))
     eq('', fn.luaeval('_A', ''))
@@ -155,7 +155,7 @@ describe('luaeval()', function()
     eq(false, fn.luaeval('_A', false))
   end)
 
-  it('correctly passes containers as argument', function()
+  it('passes containers as argument', function()
     eq({}, fn.luaeval('_A', {}))
     eq({ test = 1 }, fn.luaeval('_A', { test = 1 }))
     eq({ 4, 2 }, fn.luaeval('_A', { 4, 2 }))
@@ -187,7 +187,7 @@ describe('luaeval()', function()
     ]=]):format(expr or '"_A"', argexpr):gsub('\n', '')))
   end
 
-  it('correctly passes special dictionaries', function()
+  it('passes special dictionaries', function()
     eq({ 0, '\000\n\000' }, luaevalarg(sp('string', '["\\n", "\\n"]')))
     eq({ 0, true }, luaevalarg(sp('boolean', 1)))
     eq({ 0, false }, luaevalarg(sp('boolean', 0)))
@@ -195,7 +195,7 @@ describe('luaeval()', function()
     eq({ 0, { [''] = '' } }, luaevalarg(mapsp(sp('string', '[""]'), '""')))
   end)
 
-  it('issues an error in some cases', function()
+  it('failure modes', function()
     eq(
       'Vim(call):E5100: Cannot convert given Lua table: table should contain either only integer keys or only string keys',
       exc_exec('call luaeval("{1, foo=2}")')
@@ -205,7 +205,7 @@ describe('luaeval()', function()
     startswith('Vim(call):E5108: Lua: [string "luaeval()"]:', exc_exec('call luaeval("(nil)()")'))
   end)
 
-  it('should handle sending lua functions to viml', function()
+  it('handles sending lua functions to viml', function()
     eq(
       true,
       exec_lua [[
@@ -294,7 +294,7 @@ describe('luaeval()', function()
     matches(': dead function\n', api.nvim_get_vvar('errmsg'))
   end)
 
-  it('should handle passing functions around', function()
+  it('can pass functions around', function()
     command [[
       function VimCanCallLuaCallbacks(Concat, Cb)
         let message = a:Concat("Hello Vim", "I'm Lua")
@@ -317,7 +317,7 @@ describe('luaeval()', function()
     )
   end)
 
-  it('should handle funcrefs', function()
+  it('handles funcrefs', function()
     command [[
       function VimCanCallLuaCallbacks(Concat, Cb)
         let message = a:Concat("Hello Vim", "I'm Lua")
@@ -340,7 +340,7 @@ describe('luaeval()', function()
     )
   end)
 
-  it('should work with metatables using __call', function()
+  it('works with metatables using __call', function()
     eq(
       1,
       exec_lua [[
@@ -362,7 +362,7 @@ describe('luaeval()', function()
     )
   end)
 
-  it('should handle being called from a timer once.', function()
+  it('handles being called from a timer once.', function()
     eq(
       3,
       exec_lua [[
@@ -381,7 +381,7 @@ describe('luaeval()', function()
     )
   end)
 
-  it('should call functions once with __call metamethod', function()
+  it('calls functions once with __call metamethod', function()
     eq(
       true,
       exec_lua [[
@@ -398,7 +398,7 @@ describe('luaeval()', function()
     )
   end)
 
-  it('should work with lists using __call', function()
+  it('works with lists using __call', function()
     eq(
       3,
       exec_lua [[
@@ -429,7 +429,7 @@ describe('luaeval()', function()
     )
   end)
 
-  it('should not work with tables not using __call', function()
+  it('fails with tables not using __call', function()
     eq(
       { false, 'Vim:E921: Invalid callback argument' },
       exec_lua [[
@@ -441,7 +441,7 @@ describe('luaeval()', function()
     )
   end)
 
-  it('correctly converts containers with type_idx', function()
+  it('converts containers with type_idx', function()
     eq(5, eval('type(luaeval("{[vim.type_idx]=vim.types.float, [vim.val_idx]=0}"))'))
     eq(4, eval([[type(luaeval('{[vim.type_idx]=vim.types.dictionary}'))]]))
     eq(3, eval([[type(luaeval('{[vim.type_idx]=vim.types.array}'))]]))
@@ -463,7 +463,7 @@ describe('luaeval()', function()
     eq({}, fn.luaeval('{[vim.type_idx]=vim.types.dictionary}'))
   end)
 
-  it('correctly converts self-containing containers', function()
+  it('converts self-containing containers', function()
     api.nvim_set_var('l', {})
     eval('add(l, l)')
     eq(true, eval('luaeval("_A == _A[1]", l)'))
@@ -479,7 +479,7 @@ describe('luaeval()', function()
     eq(true, eval('luaeval("_A ~= _A.d", {"d": d})'))
   end)
 
-  it('errors out correctly when doing incorrect things in lua', function()
+  it('fails when doing incorrect things in lua', function()
     -- Conversion errors
     eq(
       'Vim(call):E5108: Lua: [string "luaeval()"]:1: attempt to call field \'xxx_nonexistent_key_xxx\' (a nil value)',
@@ -531,7 +531,7 @@ describe('v:lua', function()
     ]])
   end)
 
-  it('works in expressions', function()
+  it('in expressions', function()
     eq(7, eval('v:lua.foo(3,4,v:null)'))
     eq(true, exec_lua([[return _G.val == vim.NIL]]))
     eq(NIL, eval('v:lua.mymod.noisy("eval")'))
@@ -545,7 +545,7 @@ describe('v:lua', function()
     )
   end)
 
-  it('works when called as a method', function()
+  it('when called as a method', function()
     eq(123, eval('110->v:lua.foo(13)'))
     eq(true, exec_lua([[return _G.val == nil]]))
 
@@ -562,7 +562,7 @@ describe('v:lua', function()
     )
   end)
 
-  it('works in :call', function()
+  it('in :call', function()
     command(":call v:lua.mymod.noisy('command')")
     eq('hey command', api.nvim_get_current_line())
     eq(
@@ -571,7 +571,7 @@ describe('v:lua', function()
     )
   end)
 
-  it('works in func options', function()
+  it('in func options', function()
     local screen = Screen.new(60, 8)
     api.nvim_set_option_value('omnifunc', 'v:lua.mymod.omni', {})
     feed('isome st<c-x><c-o>')
@@ -599,7 +599,7 @@ describe('v:lua', function()
     eq(9004, eval("0 ? v:lua.require'bar'.doit() : v:lua.require'baz-quux'.doit()"))
   end)
 
-  it('throw errors for invalid use', function()
+  it('fails for invalid usage', function()
     eq(
       [[Vim(let):E15: Invalid expression: "v:lua.func"]],
       pcall_err(command, 'let g:Func = v:lua.func')
@@ -639,7 +639,7 @@ describe('v:lua', function()
     eq([[Vim:E15: Invalid expression: "v:lua.()"]], pcall_err(eval, 'v:lua.()'))
   end)
 
-  describe('invalid use in fold text', function()
+  describe('invalid usage in fold text', function()
     before_each(function()
       feed('ifoo<CR>bar<Esc>')
       command('1,2fold')

test/functional/ui/messages_spec.lua

@@ -3185,7 +3185,7 @@ describe('progress-message', function()
     setup_autocmd()
   end)
 
-  it('can be sent by nvim_echo', function()
+  it('emitted by nvim_echo', function()
     local id = api.nvim_echo(
       { { 'test-message' } },
       true,
@@ -3194,9 +3194,9 @@ describe('progress-message', function()
 
     screen:expect({
       grid = [[
-    ^                         |
+        ^                         |
-    {1:~                        }|*4
+        {1:~                        }|*4
-  ]],
+      ]],
       messages = {
         {
           content = {
@@ -3283,7 +3283,7 @@ describe('progress-message', function()
 
     -- failed status
     api.nvim_echo(
-      { { 'test-message (success)' } },
+      { { 'test-message (fail)' } },
       true,
       { kind = 'progress', title = 'TestSuit', percent = 35, status = 'failed' }
     )
@@ -3298,7 +3298,7 @@ describe('progress-message', function()
             { 'TestSuit', 9, 'ErrorMsg' },
             { ': ' },
             { ' 35% ', 19, 'WarningMsg' },
-            { 'test-message (success)' },
+            { 'test-message (fail)' },
           },
           history = true,
           id = 3,
@@ -3309,22 +3309,22 @@ describe('progress-message', function()
 
     -- cancel status
     api.nvim_echo(
-      { { 'test-message (success)' } },
+      { { 'test-message (cancel)' } },
       true,
       { kind = 'progress', title = 'TestSuit', percent = 30, status = 'cancel' }
     )
     screen:expect({
       grid = [[
-    ^                         |
+        ^                         |
-    {1:~                        }|*4
+        {1:~                        }|*4
-  ]],
+      ]],
       messages = {
         {
           content = {
             { 'TestSuit', 19, 'WarningMsg' },
             { ': ' },
             { ' 30% ', 19, 'WarningMsg' },
-            { 'test-message (success)' },
+            { 'test-message (cancel)' },
           },
           history = true,
           id = 4,