Merge pull request #25286 from rktjmp/doc-vim-schedule-wrap

docs: add more context to vim.schedule_wrap

runtime/doc/lua.txt

@@ -956,12 +956,12 @@ vim.rpcrequest({channel}, {method}, {args}, {...})          *vim.rpcrequest()*
       • {args}     any[]|nil
       • {...}      any|nil
 
-vim.schedule({callback})                                      *vim.schedule()*
+vim.schedule({fn})                                            *vim.schedule()*
-    Schedules {callback} to be invoked soon by the main event-loop. Useful to
+    Schedules {fn} to be invoked soon by the main event-loop. Useful to avoid
-    avoid |textlock| or other temporary restrictions.
+    |textlock| or other temporary restrictions.
 
     Parameters: ~
-      • {callback}  fun()
+      • {fn}  (function)
 
 vim.str_byteindex({str}, {index}, {use_utf16})           *vim.str_byteindex()*
     Convert UTF-32 or UTF-16 {index} to byte index. If {use_utf16} is not
@@ -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()*
+vim.schedule_wrap({fn})                                  *vim.schedule_wrap()*
-    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))
+<
 
     Parameters: ~
-      • {cb}  (function)
+      • {fn}  (function)
 
     Return: ~
         (function)

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

runtime/lua/vim/_meta/builtin.lua

@@ -194,10 +194,10 @@ function vim.str_utfindex(str, index) end
 --- @return string|nil Converted string if conversion succeeds, `nil` otherwise.
 function vim.iconv(str, from, to, opts) end
 
---- Schedules {callback} to be invoked soon by the main event-loop. Useful
+--- Schedules {fn} to be invoked soon by the main event-loop. Useful
 --- to avoid |textlock| or other temporary restrictions.
---- @param callback fun()
+--- @param fn function
-function vim.schedule(callback) end
+function vim.schedule(fn) end
 
 --- Wait for {time} in milliseconds until {callback} returns `true`.
 ---