docs(frontend): specialize single-payload AST field explanations

crates/frontend/editor/ast.ts

@@ -10,11 +10,11 @@ export interface Span { start: number; end: number; }
 export type AstDocument = { schema: typeof AST_SCHEMA_ID; root: AstRoot; };
 // parse_ast 按模式构造的模块、表达式或交互根，compiler 据此选择生成入口。
 // Module: 模块根，包含函数/类声明。
-// Module.body: body 保存 Program 类型的值。
+// Module.body: 当前模式选中的模块、表达式或交互根载荷，compiler 按对应构造器生成入口代码。
 // Expression: 表达式根，编译后直接返回求值结果。
-// Expression.body: body 保存 Expr 类型的值。
+// Expression.body: 当前模式选中的模块、表达式或交互根载荷，compiler 按对应构造器生成入口代码。
 // Interactive: 交互根，包含一次完整提交。
-// Interactive.body: body 保存 InteractiveInput 类型的值。
+// Interactive.body: 当前模式选中的模块、表达式或交互根载荷，compiler 按对应构造器生成入口代码。
 export type AstRoot = { kind: "Module"; data: Program; } | { kind: "Expression"; data: Expr; } | { kind: "Interactive"; data: InteractiveInput; };
 // parser 复制的名称文本与位置，用于声明、类型注解或属性名。
 // text: 拥有名称文本，不依赖输入缓冲存活。
@@ -30,9 +30,9 @@ export type Program = { declarations: Array<Decl>; span: Span; };
 export type Decl = { kind: DeclKind; span: Span; };
 // 函数与类声明的判别载荷，外层 Decl 另外保存完整跨度。
 // Function: 显式参数/返回注解与函数体，compiler 生成独立模板及源码签名；解析本身不调用函数。
-// Function.definition: definition 保存 Function 类型的值。
+// Function.definition: 函数或类的完整声明，包含其名称、成员/参数及原文范围。
 // Class: 类名、可选基类、字段和方法，compiler 检查成员后生成构类指令。
-// Class.definition: definition 保存 Class 类型的值。
+// Class.definition: 函数或类的完整声明，包含其名称、成员/参数及原文范围。
 export type DeclKind = { kind: "Function"; data: Function; } | { kind: "Class"; data: Class; };
 // 类名、可选基类、字段和方法，compiler 检查成员后生成构类指令。
 // name: 类声明名与精确位置。
@@ -63,21 +63,21 @@ export type Block = { statements: Array<Stmt>; span: Span; };
 export type Stmt = { kind: StmtKind; span: Span; };
 // 语句判别载荷，parser 选择分支，compiler 按绑定、赋值、控制流等规则处理。
 // Binding: let 新绑定，compiler 检查重名并分析右值后才标记目标已初始化。
-// Binding.binding: binding 保存 Binding 类型的值。
+// Binding.binding: let 新绑定，compiler 先分析/求右值，再登记目标初始化。
 // Assignment: 普通名称赋值，compiler 按作用域写局部槽或全局环境。
-// Assignment.assignment: assignment 保存 Assignment 类型的值。
+// Assignment.assignment: 普通名称或成员赋值的完整节点，compiler 据构造器选择槽写入或属性写入。
 // MemberAssignment: 成员写入的对象、属性名与右值，compiler 生成 StoreAttr。
-// MemberAssignment.assignment: assignment 保存 MemberAssignment 类型的值。
+// MemberAssignment.assignment: 普通名称或成员赋值的完整节点，compiler 据构造器选择槽写入或属性写入。
 // If: 条件、then 和可选 else，compiler 合并继续路径的初始化集合并生成跳转。
-// If.statement: statement 保存 IfStatement 类型的值。
+// If.statement: 条件、循环或返回节点，compiler 按构造器处理路径、跳转或帧出口。
 // While: 循环条件与体，compiler 生成回边并处理循环可能零次执行。
-// While.statement: statement 保存 WhileStatement 类型的值。
+// While.statement: 条件、循环或返回节点，compiler 按构造器处理路径、跳转或帧出口。
 // Return: 函数返回，compiler 对缺省值补 Nil；当前源码语法要求 return 后有表达式。
-// Return.statement: statement 保存 ReturnStatement 类型的值。
+// Return.statement: 条件、循环或返回节点，compiler 按构造器处理路径、跳转或帧出口。
 // Expression: 表达式载荷及完整范围，compiler 生成留下一个结果的求值序列。
-// Expression.expression: expression 保存 Expr 类型的值。
+// Expression.expression: 语句位置的表达式；函数块丢弃结果，交互根可把它作为返回值。
 // Declaration: 顶层/交互声明的种类及完整范围，compiler 按函数或类分派。
-// Declaration.declaration: declaration 保存 Decl 类型的值。
+// Declaration.declaration: 交互根中的函数/类声明，compiler 预登记名称；嵌套声明当前被拒绝。
 export type StmtKind = { kind: "Binding"; data: Binding; } | { kind: "Assignment"; data: Assignment; } | { kind: "MemberAssignment"; data: MemberAssignment; } | { kind: "If"; data: IfStatement; } | { kind: "While"; data: WhileStatement; } | { kind: "Return"; data: ReturnStatement; } | { kind: "Expression"; data: Expr; } | { kind: "Declaration"; data: Decl; };
 // let 新绑定，compiler 检查重名并分析右值后才标记目标已初始化。
 // name: let 目标名，重复声明由语义分析拒绝。
@@ -120,11 +120,11 @@ export type InteractiveInput = { statements: Array<Stmt>; span: Span; };
 export type Expr = { kind: ExprKind; span: Span; };
 // 名称、字面量、等待、运算和调用等表达式载荷，范围由外层 Expr 提供。
 // Name: 变量引用文本，compiler 决定局部槽或全局索引。
-// Name.text: text 保存 string 类型的值。
+// Name.text: 名称引用原文，由 compiler 名称分析解析到局部槽或全局名字表。
 // Number: 原始十进制拼写，保留全部位数、前导零及尾零，不转浮点。
-// Number.spelling: spelling 保存 string 类型的值。
+// Number.spelling: 原始数字拼写，compiler 构造精确数值；不把文本先转为二进制浮点。
 // String: 已解码受支持转义的拥有文本，原引号范围在外层 Expr。
-// String.value: value 保存 string 类型的值。
+// String.value: 字符串解码后的拥有文本，原引号和转义仍可通过外层范围读取。
 // Symbol: 点开头的符号名，前端可表示，当前 compiler 拒绝生成运行时值。
 // Symbol.name: 成员或符号名，不是已解析的运行时属性句柄。
 // Await: 等待子表达式，VM 执行上下文决定是否允许停放。

scripts/generate_ast.py

@@ -53,6 +53,16 @@ TYPE_NOTES = {
 FIELD_NOTES = {
     ("AstDocument", "schema"): "协议身份，wire 按 AST_SCHEMA_ID 核对；不是源码内容哈希。",
     ("AstDocument", "root"): "拥有的语法根，文档校验及编译从这里递归。",
+    ("AstRoot", "body"): "当前模式选中的模块、表达式或交互根载荷，compiler 按对应构造器生成入口代码。",
+    ("DeclKind", "definition"): "函数或类的完整声明，包含其名称、成员/参数及原文范围。",
+    ("StmtKind", "binding"): "let 新绑定，compiler 先分析/求右值，再登记目标初始化。",
+    ("StmtKind", "assignment"): "普通名称或成员赋值的完整节点，compiler 据构造器选择槽写入或属性写入。",
+    ("StmtKind", "statement"): "条件、循环或返回节点，compiler 按构造器处理路径、跳转或帧出口。",
+    ("StmtKind", "expression"): "语句位置的表达式；函数块丢弃结果，交互根可把它作为返回值。",
+    ("StmtKind", "declaration"): "交互根中的函数/类声明，compiler 预登记名称；嵌套声明当前被拒绝。",
+    ("ExprKind", "text"): "名称引用原文，由 compiler 名称分析解析到局部槽或全局名字表。",
+    ("ExprKind", "spelling"): "原始数字拼写，compiler 构造精确数值；不把文本先转为二进制浮点。",
+    ("ExprKind", "value"): "字符串解码后的拥有文本，原引号和转义仍可通过外层范围读取。",
     ("Name", "text"): "拥有名称文本，不依赖输入缓冲存活。",
     ("Program", "declarations"): "按源码顺序的声明；源码模块解析要求非空，文档结构本身不限制数量。",
     ("Decl", "kind"): "函数/类声明载荷，JSON 和类型采用 kind/data 标签。",
@@ -565,7 +575,7 @@ def editor_types(definitions, schema_id):
             # 每个构造器按稳定顺序生成，不合并名称相近但身份不同的分支。
             for variant in definition.variants:
                 if definition.simple():
-                    # 拼接当前构造器的 kind 字面量和数据对象声明。
+                    # 无载荷简单枚举直接编码为字符串，不构造 kind/data 对象。
                     value = json.dumps(variant.name)
                 # 当前分支不是无载荷简单枚举，需要构造带 kind 及可选 data 的判别对象。
                 else: