feat(paste): unify cancel and error behavior (#30476)

Before this PR, the behavior of nvim_paste is:
- When vim.paste() returns false, return false to the client, but treat
  following chunks normally (i.e. rely on the client cancelling the
  paste as expected).
- When vim.paste() throws an error, still return true to the client, but
  drain the following chunks in the stream without calling vim.paste().

There are two problems with such behavior:
- When vim.paste() errors, the client is still supposed to send the
  remaining chunks of the stream, even though they do nothing.
- Having different code paths for two uncommon but similar situations
  complicates maintenance.

This PR makes both the cancel case and the error case return false to
the client and drain the remaining chunks of the stream, which, apart
from sharing the same code path, is beneficial whether the client checks
the return value of nvim_paste or not:
- If the client checks the return value, it can avoid sending the
  following chunks needlessly after an error.
- If the client doesn't check the return value, chunks following a
  cancelled chunk won't be pasted on the server regardless, which leads
  to less confusing behavior.

1 files changed, 3 insertions, 3 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index a7c71d9a32..e7a8e788b9 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -1155,8 +1155,8 @@ nvim_paste({data}, {crlf}, {phase})                             *nvim_paste()*
 
     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, subsequent calls are ignored ("drained") until
-    the next paste is initiated (phase 1 or -1).
+    `vim.paste()`). On error or cancel, subsequent calls are ignored
+    ("drained") until the next paste is initiated (phase 1 or -1).
 
     Attributes: ~
         not allowed when |textlock| is active
@@ -1173,7 +1173,7 @@ nvim_paste({data}, {crlf}, {phase})                             *nvim_paste()*
 
     Return: ~
         • true: Client may continue pasting.
-        • false: Client must cancel the paste.
+        • false: Client should cancel the paste.
 
 nvim_put({lines}, {type}, {after}, {follow})                      *nvim_put()*
     Puts text at cursor, in any mode.