From d2257307b16da8949be931e03867985b07d10a8f Mon Sep 17 00:00:00 2001
From: Hana <andywangsy@gmail.com>
Date: Tue, 10 Sep 2024 18:08:53 +0800
Subject: [PATCH] docs: clarify loader `this.callback` usage

---
 website/docs/en/api/loader-api/context.mdx | 7 +++++++
 website/docs/zh/api/loader-api/context.mdx | 7 +++++++
 2 files changed, 14 insertions(+)

diff --git a/website/docs/en/api/loader-api/context.mdx b/website/docs/en/api/loader-api/context.mdx
index 3f1154d1adb..e8f6ccf7422 100644
--- a/website/docs/en/api/loader-api/context.mdx
+++ b/website/docs/en/api/loader-api/context.mdx
@@ -70,6 +70,13 @@ A function that can be called synchronously or asynchronously in order to return
 3. The third parameter is a source map that can be processed by the loader.
 4. The fourth parameter is ignored by Rspack and can be anything (e.g. some metadata).
 
+:::warning
+In case this function is called, you should return `undefined` to avoid ambiguous loader results.
+
+The value passed to `this.callback` will be passed to the next loader in the chain.
+Without returning its value, for example `meta`, the next loader will not receive it.
+:::
+
 ## this.clearDependencies()
 
 ```ts
diff --git a/website/docs/zh/api/loader-api/context.mdx b/website/docs/zh/api/loader-api/context.mdx
index 42500c64db8..49908eac8ad 100644
--- a/website/docs/zh/api/loader-api/context.mdx
+++ b/website/docs/zh/api/loader-api/context.mdx
@@ -73,6 +73,13 @@ function callback(
 
 第一个参数必须是 `Error` 或者 `null`，会标记当前模块为编译失败，第二个参数是一个 `string` 或者 `Buffer`，表示模块被该 Loader 处理后的文件内容，第三个参数是一个可以该 Loader 处理后的 source map，第四个参数会被 Rspack 忽略，可以是任何东西（例如一些元数据）。
 
+:::warning
+当这个函数被调用时，你应该返回 `undefined` 以避免 loader 结果的歧义。
+
+传递给 `this.callback` 的值会传递给下一个 loader。
+当没有返回值时，例如 `meta`，下一个 loader 将不会收到它。
+:::
+
 ## this.context
 
 当前模块所在的目录。