docs(compiler): explain compilation entry points and source examples

crates/compiler/examples/calls.endor

@@ -1,13 +1,21 @@
+// compiler/tests/pipeline.rs 将此文件作为模块编译，加载后由测试调用 main，检查前向全局函数查找。
 // The callee is declared after main. Parameters, locals and calls use wordcode.
+// 模块入口由宿主/测试在模块执行完成后调用；先 echo，再把局部结果交给 relay。
 function main(): String {
+    // 直接调用后面声明的 echo，返回值写入当前帧的 message 局部槽。
     let message = echo("函数调用已接通")
+    // 将局部值作为实参传给 relay，返回其结果给宿主。
     return relay(message)
 }
 
+// main 调用的中转函数；value 是当前帧参数槽，继续调用全局 echo。
 function relay(value: String): String {
+    // 普通函数调用逐层返回相同字符串，验证嵌套调用的参数传递与返回。
     return echo(value)
 }
 
+// main 和 relay 共用的恒等函数，参数值直接成为调用结果。
 function echo(value: String): String {
+    // 无额外转换，直接把参数值交给调用者。
     return value
 }

crates/compiler/examples/hello.endor

@@ -1,4 +1,5 @@
-// cli run crates/compiler/examples/hello.endor → 你好，Endor 🌱
+// compiler/tests/pipeline.rs 编译并加载本模块后调用 main，期望返回“你好，Endor 🌱”。
 function main(): String {
+    // 返回 Unicode 文本字面量，测试核对编译及 VM 返回过程保留原文。
     return "你好，Endor 🌱"
 }

crates/compiler/examples/literal.endor

@@ -1,2 +1,2 @@
-// cli eval crates/compiler/examples/literal.endor
+// compiler/tests/pipeline.rs 以 Expression 模式编译此文件，VM 执行后直接取得文本；不定义 main。
 "表达式 → 字节码 → VM"

crates/compiler/examples/number.endor

@@ -1,5 +1,9 @@
+// compiler/tests/pipeline.rs 按 Module 模式编译，执行模块后调用 main 并按精确十进制值比较。
 // Signed decimal constants retain all digits; no f64 conversion or arithmetic.
+// 由测试/宿主调用，验证长十进制带符号常量经过编译与返回仍不丢精度。
 function main(): Number {
+    // 字面量保存所有十进制数字，不先经 f64；源码负号经 signed_literal 合入精确数值拼写。
     let value = -123456789012345678901234567890.00100
+    // 返回局部槽中的数值，用于检查整个管线保持原来的精确值。
     return value
 }

crates/compiler/examples/shadowing.endor

@@ -1,13 +1,21 @@
+// compiler/tests/pipeline.rs 加载模块并调用 main，检查函数值传参及局部名优先于全局声明。
 // A parameter can shadow a module function, and functions are ordinary values.
+// main 把此全局函数作为普通值传入 invoke；实际调用时返回收到的参数。
 function echo(value: String): String {
+    // 恒等返回，不改变用于确认调用链的文本。
     return value
 }
 
+// main 调用；参数 echo 遮蔽同名模块函数，value 保存待转发的字符串。
 function invoke(echo: Callable, value: String): String {
+    // 从局部参数 echo 复制函数值，而非再次查找模块的同名全局。
     let chosen = echo
+    // 经局部 chosen 间接调用函数，把 value 作为实参并返回调用结果。
     return chosen(value)
 }
 
+// 宿主/测试入口，先取得全局 echo 函数值，再传给 invoke 的同名参数。
 function main(): String {
+    // invoke 内部用局部参数解析 echo，最终应原样返回这段文本。
     return invoke(echo, "局部名称优先")
 }