Updated docs.

5 files changed, 121 insertions, 3 deletions

diff --git a/doc/docs/zh/doc/advanced/do.md b/doc/docs/zh/doc/advanced/do.md
index a2d5d19..b3f61af 100644
--- a/doc/docs/zh/doc/advanced/do.md
+++ b/doc/docs/zh/doc/advanced/do.md
@@ -20,7 +20,27 @@ print var -- 这里是nil
 
 </YueDisplay>
 
-&emsp;&emsp;月之脚本的 **do** 也可以用作表达式。允许你将多行代码的处理合并为一个表达式，并将 do 语句代码块的最后一个语句作为表达式返回的结果。
+&emsp;&emsp;月之脚本的 **do** 也可以用作表达式。允许你将多行代码的处理合并为一个表达式，并将 do 语句代码块的最后一个语句作为表达式返回的结果。`do` 表达式支持通过 `break` 打断执行流并提前返回多个值。
+
+```yuescript
+status, value = do
+  n = 12
+  if n > 10
+    break "large", n
+  break "small", n
+```
+
+<YueDisplay>
+
+```yue
+status, value = do
+  n = 12
+  if n > 10
+    break "large", n
+  break "small", n
+```
+
+</YueDisplay>
 
 ```yuescript
 counter = do
diff --git a/doc/docs/zh/doc/control-flow/for-loop.md b/doc/docs/zh/doc/control-flow/for-loop.md
index 52180b7..97e66f9 100644
--- a/doc/docs/zh/doc/control-flow/for-loop.md
+++ b/doc/docs/zh/doc/control-flow/for-loop.md
@@ -86,7 +86,7 @@ doubled_evens = for i = 1, 20
 
 </YueDisplay>
 
-&emsp;&emsp;此外，for 循环还支持带返回值的 break 语句，这样循环本身就可以作为一个表达式，在满足条件时提前退出并返回有意义的结果。
+&emsp;&emsp;此外，for 循环还支持带返回值的 break 语句，这样循环本身就可以作为一个表达式，在满足条件时提前退出并返回有意义的结果。for 循环表达式支持 `break` 返回多个值。
 
 &emsp;&emsp;例如，查找第一个大于 10 的数字：
 
@@ -104,6 +104,20 @@ first_large = for n in *numbers
 
 </YueDisplay>
 
+```yuescript
+key, score = for k, v in pairs data
+  break k, v * 10 if k == "target"
+```
+
+<YueDisplay>
+
+```yue
+key, score = for k, v in pairs data
+  break k, v * 10 if k == "target"
+```
+
+</YueDisplay>
+
 &emsp;&emsp;你还可以结合 for 循环表达式与 continue 语句来过滤值。
 
 &emsp;&emsp;注意出现在函数体末尾的 for 循环，不会被当作是一个表达式并将循环结果累积到一个列表中作为返回值（相反，函数将返回 nil）。如果要函数末尾的循环转换为列表表达式，可以显式地使用返回语句加 for 循环表达式。
diff --git a/doc/docs/zh/doc/control-flow/while-loop.md b/doc/docs/zh/doc/control-flow/while-loop.md
index 3c624fe..0138d85 100644
--- a/doc/docs/zh/doc/control-flow/while-loop.md
+++ b/doc/docs/zh/doc/control-flow/while-loop.md
@@ -45,7 +45,25 @@ until running == false do my_function!
 
 </YueDisplay>
 
-&emsp;&emsp;像 for 循环的语法一样，while 循环也可以作为一个表达式使用。为了使函数返回 while 循环的累积列表值，必须明确使用返回语句返回 while 循环表达式。
+&emsp;&emsp;像 for 循环的语法一样，while 循环也可以作为一个表达式使用。while / until 循环表达式支持 `break` 返回多个值。
+
+```yuescript
+value, doubled = while true
+  n = get_next!
+  break n, n * 2 if n > 10
+```
+
+<YueDisplay>
+
+```yue
+value, doubled = while true
+  n = get_next!
+  break n, n * 2 if n > 10
+```
+
+</YueDisplay>
+
+&emsp;&emsp;为了使函数返回 while 循环的累积列表值，必须明确使用返回语句返回 while 循环表达式。
 
 ## repeat 循环
 
@@ -70,3 +88,25 @@ until i == 0
 ```
 
 </YueDisplay>
+
+&emsp;&emsp;repeat 循环表达式同样支持 `break` 返回多个值：
+
+```yuescript
+i = 1
+value, scaled = repeat
+  break i, i * 100 if i > 3
+  i += 1
+until false
+```
+
+<YueDisplay>
+
+```yue
+i = 1
+value, scaled = repeat
+  break i, i * 100 if i > 3
+  i += 1
+until false
+```
+
+</YueDisplay>
diff --git a/doc/docs/zh/doc/advanced/module.md b/doc/docs/zh/doc/language-basics/module.md
index 6c90f0e..6c90f0e 100644
--- a/doc/docs/zh/doc/advanced/module.md
+++ b/doc/docs/zh/doc/language-basics/module.md
diff --git a/doc/docs/zh/doc/objects/with-statement.md b/doc/docs/zh/doc/objects/with-statement.md
index 0925050..338e2cc 100644
--- a/doc/docs/zh/doc/objects/with-statement.md
+++ b/doc/docs/zh/doc/objects/with-statement.md
@@ -44,6 +44,50 @@ file = with File "favorite_foods.txt"
 
 </YueDisplay>
 
+`with` 表达式支持 `break` 返回一个值：
+
+```yuescript
+result = with obj
+  break .value
+```
+
+<YueDisplay>
+
+```yue
+result = with obj
+  break .value
+```
+
+</YueDisplay>
+
+在 `with` 中使用 `break value` 后，`with` 表达式将不再返回其目标对象，而是返回 `break` 给出的值。
+
+```yuescript
+a = with obj
+  .x = 1
+-- a 是 obj
+
+b = with obj
+  break .x
+-- b 是 .x，不是 obj
+```
+
+<YueDisplay>
+
+```yue
+a = with obj
+  .x = 1
+-- a 是 obj
+
+b = with obj
+  break .x
+-- b 是 .x，不是 obj
+```
+
+</YueDisplay>
+
+与 `for` / `while` / `repeat` / `do` 不同，`with` 只支持一个 break 返回值。
+
 或者…
 
 ```yuescript