2 files changed, 30 insertions, 12 deletions
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index 7b5570cc99..cb864bd974 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -208,8 +208,10 @@ vim.inspect = vim.inspect
 do
   local tdots, tick, got_line1, undo_started, trailing_nl = 0, 0, false, false, false
 
-  --- Paste handler, invoked by |nvim_paste()| when a conforming UI
-  --- (such as the |TUI|) pastes text into the editor.
+  --- Paste handler, invoked by |nvim_paste()|.
+  ---
+  --- Note: This is provided only as a "hook", don't call it directly; call |nvim_paste()| instead,
+  --- which arranges redo (dot-repeat) and invokes `vim.paste`.
   ---
   --- Example: To remove ANSI color codes when pasting:
   ---
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index b53a9ad321..a9430078a8 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -744,11 +744,6 @@ function vim.api.nvim_buf_set_option(buffer, name, value) end
 --- `start_row = end_row = row` and `start_col = end_col = col`. To delete the
 --- text in a range, use `replacement = {}`.
 ---
---- Prefer `nvim_buf_set_lines()` if you are only adding or deleting entire
---- lines.
----
---- Prefer `nvim_put()` if you want to insert text at the cursor position.
----
 --- @param buffer integer Buffer handle, or 0 for current buffer
 --- @param start_row integer First line index
 --- @param start_col integer Starting column (byte offset) on first line
@@ -1484,6 +1479,9 @@ function vim.api.nvim_get_vvar(name) end
 --- input buffer and the call is non-blocking (input is processed
 --- asynchronously by the eventloop).
 ---
+--- To input blocks of text, `nvim_paste()` is much faster and should be
+--- preferred.
+---
 --- On execution error: does not fail, but updates v:errmsg.
 ---
 --- @param keys string to be typed
@@ -1809,17 +1807,34 @@ function vim.api.nvim_parse_cmd(str, opts) end
 --- @return table<string,any>
 function vim.api.nvim_parse_expression(expr, flags, highlight) end
 
---- Pastes at cursor, in any mode.
+--- Pastes at cursor (in any mode), and sets "redo" so dot (`.`) will repeat
+--- the input. UIs call this to implement "paste", but it's also intended for
+--- use by scripts to input large, dot-repeatable blocks of text (as opposed
+--- to `nvim_input()` which is subject to mappings/events and is thus much
+--- slower).
 ---
---- Invokes the `vim.paste` handler, which handles each mode appropriately.
---- Sets redo/undo. Faster than `nvim_input()`. Lines break at LF ("\n").
+--- Invokes the `vim.paste()` handler, which handles each mode appropriately.
 ---
 --- Errors ('nomodifiable', `vim.paste()` failure, …) are reflected in `err`
 --- but do not affect the return value (which is strictly decided by
 --- `vim.paste()`). On error or cancel, subsequent calls are ignored
 --- ("drained") until the next paste is initiated (phase 1 or -1).
 ---
---- @param data string Multiline input. May be binary (containing NUL bytes).
+--- Useful in mappings and scripts to insert multiline text. Example:
+---
+--- ```vim
+---     vim.keymap.set('n', 'x', function()
+---       vim.api.nvim_paste([[
+---         line1
+---         line2
+---         line3
+---       ]], false, -1)
+---     end, { buffer = true })
+--- ```
+---
+---
+--- @param data string Multiline input. Lines break at LF ("\n"). May be binary
+---             (containing NUL bytes).
 --- @param crlf boolean Also break lines at CR and CRLF.
 --- @param phase integer -1: paste in a single call (i.e. without streaming). To
 ---              "stream" a paste, call `nvim_paste` sequentially with these
@@ -1830,7 +1845,8 @@ function vim.api.nvim_parse_expression(expr, flags, highlight) end
 --- @return boolean
 function vim.api.nvim_paste(data, crlf, phase) end
 
---- Puts text at cursor, in any mode.
+--- Puts text at cursor, in any mode. For dot-repeatable input, use
+--- `nvim_paste()`.
 ---
 --- Compare `:put` and `p` which are always linewise.
 ---