docs: clarify vim.schedule_wrap behaviour

- Remove the usage of the term "defer" to avoid confusion with
  `vim.defer_fn`, which also calls `vim.schedule_wrap` internally.
- Explicitly state that `vim.schedule_wrap` returns a function in the
  text.
- Mention that arguments are passed along.
- Include a usage example.
- Rename param to `fn`.

2 files changed, 27 insertions, 7 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index efba10b86f..14df45cc8c 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1714,11 +1714,20 @@ vim.region({bufnr}, {pos1}, {pos2}, {regtype}, {inclusive})
         `endcol` is exclusive, and whole lines are returned as
         `{startcol,endcol} = {0,-1}`.
 
-vim.schedule_wrap({cb})                                  *vim.schedule_wrap()*
-    Defers callback `cb` until the Nvim API is safe to call.
+vim.schedule_wrap({fn})                                  *vim.schedule_wrap()*
+    Returns a function which calls {fn} via |vim.schedule()|.
+
+    The returned function passes all arguments to {fn}.
+
+    Example: >lua
+        function notify_readable(_err, readable)
+          vim.notify("readable? " .. tostring(readable))
+        end
+        vim.uv.fs_access(vim.fn.stdpath("config"), "R", vim.schedule_wrap(notify_readable))
+<
 
     Parameters: ~
-      • {cb}  (function)
+      • {fn}  (function)
 
     Return: ~
         (function)
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index 8322777633..e4a2dadb09 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -316,18 +316,29 @@ do
   end
 end
 
---- Defers callback `cb` until the Nvim API is safe to call.
+--- Returns a function which calls {fn} via |vim.schedule()|.
+---
+--- The returned function passes all arguments to {fn}.
+---
+--- Example:
+---
+--- ```lua
+--- function notify_readable(_err, readable)
+---   vim.notify("readable? " .. tostring(readable))
+--- end
+--- vim.uv.fs_access(vim.fn.stdpath("config"), "R", vim.schedule_wrap(notify_readable))
+--- ```
 ---
 ---@see |lua-loop-callbacks|
 ---@see |vim.schedule()|
 ---@see |vim.in_fast_event()|
----@param cb function
+---@param fn function
 ---@return function
-function vim.schedule_wrap(cb)
+function vim.schedule_wrap(fn)
   return function(...)
     local args = vim.F.pack_len(...)
     vim.schedule(function()
-      cb(vim.F.unpack_len(args))
+      fn(vim.F.unpack_len(args))
     end)
   end
 end