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`.
This commit is contained in:
Oliver Marriott 2023-09-21 15:53:05 +10:00
parent f094db0e5c
commit f413597f44
2 changed files with 27 additions and 7 deletions

View File

@ -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)

View File

@ -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