From 0db1b418525b9977cc0154a7d24cf55f86f622c9 Mon Sep 17 00:00:00 2001
From: sxyazi <sxyazi@gmail.com>
Date: Mon, 19 Feb 2024 20:01:28 +0800
Subject: [PATCH] docs: add more details about `ya.sync()` and its usage

---
 docs/plugins/overview.md | 13 ++++++++++++-
 docs/plugins/utils.md    |  2 +-
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/docs/plugins/overview.md b/docs/plugins/overview.md
index 22d6c51f..dee7ce5b 100644
--- a/docs/plugins/overview.md
+++ b/docs/plugins/overview.md
@@ -121,7 +121,6 @@ You can also obtain a small amount of app data from the sync context by calling
 
 ```lua
 -- ~/.config/yazi/plugins/my-async-plugin.yazi/init.lua
-
 local get_hovered_url = ya.sync(function(a, b)
 	-- You can access all app data through the `cx`,
 	-- within the `sync()` block, in an async plugin
@@ -138,6 +137,18 @@ return {
 }
 ```
 
+Note that `ya.sync()` call must be at the top level, and do not use it in sync plugins, as these are undefined behaviors that may lead to unexpected results:
+
+```lua
+-- Wrong !!!
+local get_hovered_url
+if some_condition then
+	get_hovered_url = ya.sync(function(a, b)
+		-- ...
+	end)
+end
+```
+
 ## Interface
 
 ### Previewer
diff --git a/docs/plugins/utils.md b/docs/plugins/utils.md
index f0a031be..0a82ad5c 100644
--- a/docs/plugins/utils.md
+++ b/docs/plugins/utils.md
@@ -94,7 +94,7 @@ Append messages to [the log file](./overview.md#logging) at the error level:
 
 ### `sync(fn)`
 
-TODO
+See [Async context](/docs/plugins/overview.md#async-context).
 
 ### `preview_code(opts)`