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`.

1 files changed, 12 insertions, 3 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)