docs: lsp, misc

- Problem: It's not clear for new plugin developers that `:help` uses a help-tags file for searching the docs, generated by `:helptags`. - Solution: Hint to the |:helptags| docs for regenerating the tags file for their freshly written documentation. Co-authored-by: Yochem van Rosmalen <git@yochem.nl>
2025-09-05 19:08:15 +00:00 · 2025-08-24 23:12:46 -04:00
parent de950f8272
commit 9c3099f0cf
25 changed files with 194 additions and 112 deletions
--- a/runtime/doc/api-ui-events.txt
+++ b/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:
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -1385,9 +1385,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
-    appropriate. Example: library first identifies the channel, then a plugin
-    using that library later identifies itself.
+    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.

    Attributes: ~
        |RPC| only
@@ -3324,8 +3324,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
-                   interaction with fold lines is subject to change) >
+                 • on_line: (deprecated, use on_range instead) >
                    ["line", winid, bufnr, row]
 <
                 • on_range: called for each buffer range being redrawn. Range
--- a/runtime/doc/change.txt
+++ b/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
-works well depends on the type of selection and the type of the text in the
-register.  With blockwise selection it also depends on the size of the block
-and whether the corners are on an existing character.  (Implementation detail:
-it actually works by first putting the register after the selection and then
-deleting the selection.)
-With |p| the previously selected text is put in the unnamed register (and
-possibly the selection and/or clipboard).  This is useful if you want 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
-clipboard), you can repeat the same change. But the deleted text cannot be
-used.  If you do need it you can use |p| with another register.  E.g., yank
-the text to copy, Visually select the text to replace and use "0p .  You can
-repeat this as many times as you like, and the unnamed register will be
-changed each time.
+replace the selected text with the contents of the register.  How this
+works depends on the type of selection and the text. With blockwise selection
+it also depends on the size of the block and whether the corners are on an
+existing character.  (Implementation detail: it actually works by first
+putting the register after the selection and then deleting the selection.)
+									 *v_p*
+|p| in Visual mode puts text and sets the default register (unnamed,
+selection, or clipboard) to the previously-selected text.  Useful if you want
+to put that text somewhere else.  But you cannot repeat the same change.
+									 *v_P*
+|P| in Visual mode puts text without setting the default register. You can
+repeat the change, but the deleted text cannot be used.  If you do need it you
+can use |p| with another register.  E.g., yank the text to copy, Visually
+select the text to replace and use "0p .  You can repeat this as many times as
+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
--- a/runtime/doc/develop.txt
+++ b/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"
--- a/runtime/doc/insert.txt
+++ b/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
-		(A-Z,a-z,0-9,+) text is inserted literally like pasting with
-		"p". For other registers, the text is inserted as if you typed
-		it, but mappings and abbreviations are not used.  If you have
-		options like 'textwidth', 'formatoptions', or 'autoindent'
-		set, this will influence what will be inserted. This is
-		different from what happens with the "p" command and pasting
-		with the mouse.
+		with named or clipboard registers (A-Z,a-z,0-9,+) text is
+		inserted literally like pasting with "p". For other registers,
+		the text is inserted as if you typed it, but mappings and
+		abbreviations are not used.  If you have options like
+		'textwidth', 'formatoptions', or 'autoindent' set, this will
+		influence what will be inserted. This is different from what
+		happens with the "p" command and pasting with the mouse.
 		Special registers:
 			'"'	the unnamed register, containing the text of
 				the last delete or yank
--- a/runtime/doc/lsp.txt
+++ b/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: ~
--- a/runtime/doc/lua-guide.txt
+++ b/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
-operate Nvim. It assumes some familiarity with the (non-Lua) basics of Nvim
-(commands, options, mappings, autocommands), which are covered in the
+This guide introduces the basics of everyday Lua usage for configuring and
+controlling Nvim. It assumes some familiarity with the (non-Lua) basics of
+Nvim (commands, options, mappings, autocommands), which are covered in the
 |user-manual|.

 This is not a comprehensive encyclopedia of all available features. Think of
--- a/runtime/doc/lua-plugin.txt
+++ b/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

--- a/runtime/doc/message.txt
+++ b/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|
-used to report the state of long-running tasks.
+Plugins and core Nvim features can emit "progress" |ui-messages| to report the
+state of long-running tasks.

-Progress messages are created or updated using |nvim_echo()| with `kind='progress'`
-and the related options. Each message has a unique `msg_id`. A subsequent
-message with the same `msg_id` replaces the older one.
+Create or update a progress-message by calling |nvim_echo()| with
+`kind='progress'`. Each message has a unique message-id, returned by
+`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: >
-    local id = vim.api.nvim_echo({{'searching...'}}, true,
-          {kind='progress', status='running', percent=10, title="term"})
-    vim.api.nvim_echo({{'searching'}}, true,
-          {id=id, kind='progress', status='running', percent=50, title="term"})
-    vim.api.nvim_echo({{'done'}}, true,
-          {id=id, kind='progress', status='success', percent=100, title="term"})
+Example: >lua
+    local progress = {
+      kind = 'progress',
+      status = 'running',
+      percent = 10,
+      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|

--- a/runtime/doc/news.txt
+++ b/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
-  as typed. To get the old behavior you can use `<C-R>=@x`.
+- |i_CTRL-R| inserts named/clipboard registers (A-Z,a-z,0-9+) literally, like
+  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

--- a/runtime/doc/syntax.txt
+++ b/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'.
--- a/runtime/doc/vim_diff.txt
+++ b/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
-  as typed. To get the old behavior you can use `<C-R>=@x`.
+- |i_CTRL-R| inserts named/clipboard registers (A-Z,a-z,0-9+) literally, like
+  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
--- a/runtime/lua/vim/_meta/api.lua
+++ b/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.
---     (The interaction with fold lines is subject to change)
+--- - on_line: (deprecated, use on_range instead)
 ---   ```
 ---     ["line", winid, bufnr, row]
 ---   ```
--- a/runtime/lua/vim/lsp/inline_completion.lua
+++ b/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')
--- a/scripts/cliff.toml
+++ b/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 fixes/features commits.\n
+Following is a list of commits (fixes/features only) in this release.\n
+See `:help news` in Nvim for release notes.\n
 """
 # template for the changelog body
 # https://github.com/Keats/tera
--- a/scripts/release.sh
+++ b/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"
--- a/src/gen/gen_help_html.lua
+++ b/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,
--- a/src/nvim/README.md
+++ b/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.
--- a/src/nvim/api/extmark.c
+++ b/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.
-///                 (The interaction with fold lines is subject to change)
+///             - on_line: (deprecated, use on_range instead)
 ///               ```
 ///                 ["line", winid, bufnr, row]
 ///               ```
--- a/src/nvim/api/vim.c
+++ b/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
--- a/src/nvim/highlight.h
+++ b/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.
--- a/src/nvim/message.c
+++ b/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)
 {
--- a/test/functional/editor/mode_insert_spec.lua
+++ b/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"')
--- a/test/functional/lua/luaeval_spec.lua
+++ b/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')
--- a/test/functional/ui/messages_spec.lua
+++ b/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,