1 files changed, 27 insertions, 0 deletions

diff --git a/doc/docs/doc/README.md b/doc/docs/doc/README.md
index c275c52..dac96ee 100755
--- a/doc/docs/doc/README.md
+++ b/doc/docs/doc/README.md
@@ -29,6 +29,16 @@ inventory =
     * name: "bread"
       count: 3
 
+-- list comprehension
+map = (arr, action) ->
+  [action item for item in *arr]
+
+filter = (arr, cond) ->
+  [item for item in *arr when cond item]
+
+reduce = (arr, init, action): init ->
+  init = action init, item for item in *arr
+
 -- pipe operator
 [1, 2, 3]
   |> map (x) -> x * 2
@@ -2324,6 +2334,23 @@ doubled_evens = for i = 1, 20
 </pre>
 </YueDisplay>
 
+In addition, for loops support break with a return value, allowing the loop itself to be used as an expression that exits early with a meaningful result.
+
+For example, to find the first number greater than 10:
+
+```moonscript
+first_large = for n in *numbers
+  break n if n > 10
+```
+<YueDisplay>
+<pre>
+first_large = for n in *numbers
+  break n if n > 10
+</pre>
+</YueDisplay>
+
+This break-with-value syntax enables concise and expressive search or early-exit patterns directly within loop expressions.
+
 You can also filter values by combining the for loop expression with the continue statement.
 
 For loops at the end of a function body are not accumulated into a table for a return value (Instead the function will return nil). Either an explicit return statement can be used, or the loop can be converted into a list comprehension.