doc: mention that defer_fn applies schedule_wrap (#12601)

2 files changed, 7 insertions, 0 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 0ee63eb523..af0ac6ca9f 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -415,6 +415,8 @@ To avoid the error use |vim.schedule_wrap()| to defer the callback: >
       vim.api.nvim_command('echomsg "test"')
     end))
 
+(For one-shot timers, see |vim.defer_fn()|, which automatically adds the wrapping.)
+
 Example: repeating timer
     1. Save this code to a file.
     2. Execute it with ":luafile %". >
@@ -859,6 +861,9 @@ vim.defer_fn({fn}, {timeout})                                    *vim.defer_fn*
     Defers calling {fn} until {timeout} ms passes.  Use to do a one-shot timer
     that calls {fn}.
 
+    Note: The {fn} is |schedule_wrap|ped automatically, so API functions are
+    safe to call.
+
     Parameters: ~
         {fn}        Callback to call once {timeout} expires
         {timeout}   Time in ms to wait before calling {fn}
diff --git a/src/nvim/lua/vim.lua b/src/nvim/lua/vim.lua
index 771ec971b7..18256242e8 100644
--- a/src/nvim/lua/vim.lua
+++ b/src/nvim/lua/vim.lua
@@ -467,6 +467,8 @@ end
 --- Defers calling `fn` until `timeout` ms passes.
 ---
 --- Use to do a one-shot timer that calls `fn`
+--- Note: The {fn} is |schedule_wrap|ped automatically, so API functions are
+--- safe to call.
 --@param fn Callback to call once `timeout` expires
 --@param timeout Number of milliseconds to wait before calling `fn`
 --@return timer luv timer object