From f70924b4a7555cb6c50c96c0b1c14c9c7f3ad11d Mon Sep 17 00:00:00 2001 From: Codex Bot Date: Sun, 15 Nov 2026 19:48:11 +0800 Subject: [PATCH] docs(frontend): specialize single-payload AST field explanations --- crates/frontend/editor/ast.ts | 32 ++++++++++++++++---------------- scripts/generate_ast.py | 12 +++++++++++- 2 files changed, 27 insertions(+), 17 deletions(-) diff --git a/crates/frontend/editor/ast.ts b/crates/frontend/editor/ast.ts index 9b2982a..8bc7387 100644 --- a/crates/frontend/editor/ast.ts +++ b/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; 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; 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; 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 执行上下文决定是否允许停放。 diff --git a/scripts/generate_ast.py b/scripts/generate_ast.py index 54611d7..45b38bd 100644 --- a/scripts/generate_ast.py +++ b/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: