docs: explain Tessera modules and execution flows in Chinese

src/runtime/endor_script.rs

@@ -1,3 +1,6 @@
+//! 区分完整 Module 与顶层 Script，并保留输入源码位置。
+//! 解析包装或片段拼接产生的 span 偏移要递归修正，保证诊断和 Sources 视图仍指向用户原始行列。
+//!
 //! Feed a source snapshot to Aster's existing module or interactive entry points.
 //! Statement syntax, tokens and ASTs all remain Aster-owned. The host only batches
 //! complete interactive inputs, just as a REPL feeds consecutive inputs to a VM.
@@ -7,12 +10,14 @@ use frontend::{
     ast::{AstRoot, Decl, DeclKind, Expr, ExprKind, InteractiveInput, Stmt, StmtKind},
 };
 
+/// 待编译输入是完整模块还是顶层脚本；两者保留不同根结构但使用统一后续接口。
 pub enum SourcePlan {
     Module(AstRoot),
     Script(Vec<AstRoot>),
 }
 
 impl SourcePlan {
+    /// 按输入计划返回需要编译的语法根，隐藏 Script 与 Module 组织差异。
     pub fn roots(&self) -> &[AstRoot] {
         match self {
             Self::Module(root) => std::slice::from_ref(root),
@@ -21,6 +26,7 @@ impl SourcePlan {
     }
 }
 
+/// 把外部源码或属性表示转换为内部枚举/结构，并反馈不支持的输入。
 pub fn parse(source: &SourceUnit) -> Result<SourcePlan> {
     if let Ok(module) = frontend::parse_source_ast(source, ParseMode::Module) {
         return Ok(SourcePlan::Module(module));
@@ -78,11 +84,13 @@ pub fn parse(source: &SourceUnit) -> Result<SourcePlan> {
     Ok(SourcePlan::Script(roots))
 }
 
+/// 递归调整对应语法节点的源码范围，保持片段解析后的错误位置仍指向原输入。
 fn shift_span(span: &mut Span, offset: usize) {
     span.start += offset;
     span.end += offset;
 }
 
+/// 递归调整对应语法节点的源码范围，保持片段解析后的错误位置仍指向原输入。
 fn shift_input(input: &mut InteractiveInput, offset: usize) {
     shift_span(&mut input.span, offset);
     for statement in &mut input.statements {
@@ -90,6 +98,7 @@ fn shift_input(input: &mut InteractiveInput, offset: usize) {
     }
 }
 
+/// 递归调整对应语法节点的源码范围，保持片段解析后的错误位置仍指向原输入。
 fn shift_statement(statement: &mut Stmt, offset: usize) {
     shift_span(&mut statement.span, offset);
     match &mut statement.kind {
@@ -120,6 +129,7 @@ fn shift_statement(statement: &mut Stmt, offset: usize) {
     }
 }
 
+/// 递归调整对应语法节点的源码范围，保持片段解析后的错误位置仍指向原输入。
 fn shift_declaration(declaration: &mut Decl, offset: usize) {
     shift_span(&mut declaration.span, offset);
     match &mut declaration.kind {
@@ -142,6 +152,7 @@ fn shift_declaration(declaration: &mut Decl, offset: usize) {
     }
 }
 
+/// 递归调整对应语法节点的源码范围，保持片段解析后的错误位置仍指向原输入。
 fn shift_function(function: &mut frontend::ast::Function, offset: usize) {
     shift_span(&mut function.span, offset);
     shift_span(&mut function.name.span, offset);
@@ -157,6 +168,7 @@ fn shift_function(function: &mut frontend::ast::Function, offset: usize) {
     }
 }
 
+/// 递归调整对应语法节点的源码范围，保持片段解析后的错误位置仍指向原输入。
 fn shift_expression(expression: &mut Expr, offset: usize) {
     shift_span(&mut expression.span, offset);
     match &mut expression.kind {