From a5bd741aee49fdc63bf37a19d9e37223e53580ea Mon Sep 17 00:00:00 2001
From: harehare <harehare1110@gmail.com>
Date: Tue, 27 Oct 2026 20:33:26 +0900
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs(lang):=20document=20termina?=
 =?UTF-8?q?tors=20for=20nested=20functions?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A function returning a function needs `;;` (or `end`) because a single `;` closes only the inner one, and the outer body then swallows the rest of the program without an error.
---
 docs/books/src/reference/functions.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/docs/books/src/reference/functions.md b/docs/books/src/reference/functions.md
index 405285b47..c70112ae6 100644
--- a/docs/books/src/reference/functions.md
+++ b/docs/books/src/reference/functions.md
@@ -239,6 +239,29 @@ let sum_all = fn(*args): sum(args);
 # => 6
 ```
 
+### Nested Functions
+
+Each function body needs its own terminator. A function that returns a function needs two:
+
+```
+let mk = fn(i): fn(): i;; | [mk(1), mk(2)] | map(fn(g): g();)
+# => [1, 2]
+```
+
+With a single `;`, the inner function is closed but the outer one is not. The outer body then keeps going and swallows the rest of the program, so nothing after it runs and no error is reported:
+
+```
+let mk = fn(i): fn(): i; | 5
+# => (no output)
+```
+
+Use `end` for the outer function to make the nesting explicit:
+
+```
+let mk = fn(i): fn(): i; end | 5
+# => 5
+```
+
 ## Rules
 
 - Parameters with default values must come after parameters without default values