docs: 添加 Rustdoc 注释

2026-08-05 21:46:47 +08:00
parent bbdfca1a1c
commit f461235f04
158 changed files with 1440 additions and 15 deletions
@@ -1 +1,2 @@
+//! 类编译核心预留模块（当前为空，为后续类相关公共状态预留位置）。

@@ -1,3 +1,7 @@
+//! class 声明整体 emit：驱动头、原型、方法、字段各阶段，组装最终类对象。
+//!
+//! 函数：`emit_class`。
+
 use crate::{CompileCtx, Emitter, FunctionBodyContext};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,5 @@
+//! 类静态字段/元素 emit：`emit_class_static_elements`。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::operand::Operand;
 use oxide_parser::{ClassElement, PropertyKey};
@@ -1,3 +1,5 @@
+//! 类头 emit：类名绑定、继承链（`extends`）设置，见 `emit_class_header`。
+
 use crate::{CompileCtx, Emitter};

 impl Emitter {
@@ -1,3 +1,6 @@
+//! 类方法 emit：`emit_class_methods` 逐方法构造，`emit_class_method_function`
+//! 负责单个方法函数体（含 `super` 与 home object）。
+
 use crate::{CompileCtx, Emitter, FunctionBodyContext};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,5 @@
+//! 类编译域：class 声明的整体 emit 拆分为头/原型/方法/字段等子模块。
+
 pub mod core;
 pub mod emit;
 pub mod field;
@@ -1,3 +1,5 @@
+//! 类原型对象构造：`emit_class_prototype` 建立 `Class.prototype` 与属性初始化。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,9 @@
+//! 闭包捕获分析（AST 级，emit 前完成，时序无关）。
+//!
+//! 收集本函数绑定的名字（own_bindings）与被嵌套函数捕获的名字
+//! （captured_bindings → cell_idx，按名排序稳定跨 run），为 MAKE_CELL /
+//! CELL_GET / CELL_SET 与子函数 upvalue cell_idx 提供统一依据。
+
 use std::collections::{BTreeMap, HashSet};

 use oxide_bytecode::module::UpvalueCapture;
@@ -1,3 +1,10 @@
+//! emit：AST → IR 代码生成（parse → IR → bytecode 中段）。
+//!
+//! `Emitter` 提供各语法域的 emit_* 方法；核心状态集中在 `CompileCtx`：
+//! 执行流字段（insts/registers/constants/labels）平铺其上，标识符绑定与
+//! 闭包捕获分别下沉到 `SymbolTable` / `captured_bindings`。产出分域组合的
+//! `IRFunction`，由 `oxide_ir::lower` 降为 bytecode。
+
 use std::collections::{BTreeMap, HashMap, HashSet};

 use oxide_bytecode::module::UpvalueCapture;
@@ -9,16 +16,23 @@ use oxide_ir::IRFunction;
 use crate::emit_ctx::{LabelCtx, ScopeCtx};
 use crate::symbol_table::{Binding, ScopeKind, SymbolTable};

+/// 常量池项（bytecode module 类型）re-export，供调用方构造常量。
 pub use oxide_bytecode::module::Constant;
+/// 变量声明种类（var/let/const），re-export 自 parser。
 pub use oxide_parser::VariableDeclarationKind;
+/// AST 语法树节点与运算符类型，re-export 自 parser。
 pub use oxide_parser::{AssignmentOperator, BinaryOperator, Expression, Statement, UnaryOperator};

+/// 编译入口（marker 类型）。方法按语法域组织在 `impl Emitter` 中。
 pub struct Emitter;

+/// 判断 f64 是否为整数值且在 i32 范围内（整数常量编码用）。
 pub fn is_int_literal(value: f64) -> bool {
    value.fract() == 0.0 && value >= i32::MIN as f64 && value <= i32::MAX as f64
 }

+/// 判断表达式是否无副作用（字面量/标识符/纯二元运算等）。
+/// 用于可丢弃值的优化路径。
 pub fn is_side_effect_free(expr: &Expression) -> bool {
    let mut stack = vec![expr];
    while let Some(expr) = stack.pop() {
@@ -120,6 +134,8 @@ pub struct LabelScope {
    pub(crate) continue_label: Option<LabelId>,
 }

+/// 单函数编译上下文：执行流 + 作用域 + 闭包捕获的聚合状态。
+/// 指令、常量池、寄存器分配平铺于此，作用域/绑定见 `ScopeCtx`，跳转见 `LabelCtx`。
 pub struct CompileCtx {
    pub(crate) insts: Vec<Inst>,
    pub(crate) constants: Vec<Constant>,
@@ -152,13 +168,18 @@ pub struct CompileCtx {
    pub(crate) const_overflow: bool,
 }

+/// 函数体编译上下文：决定 `this`/`super` 绑定与参数前导（prologue）形态。
 #[derive(Clone, Copy)]
 pub enum FunctionBodyContext {
+    /// 普通函数：自身 `this`、独立作用域。
    Ordinary,
+    /// 箭头函数：词法捕获外层 `this`，不生成参数前导。
    Arrow,
+    /// 类元素方法：按类语义处理 `super` 与 home object。
    ClassElement,
 }

+/// 参数规格：普通形参为标识符，解构形参用合成名 + 原始 pattern。
 pub enum ParamSpec<'a> {
    Identifier(String),
    Pattern {
@@ -513,6 +534,7 @@ impl ConstantKey {
 }

 impl Emitter {
+    /// 构造空 `Emitter`（无内部状态，所有状态在 `CompileCtx` 中）。
    pub fn new() -> Self {
        Self
    }
@@ -1,3 +1,6 @@
+//! 赋值表达式 emit：简单 `=`、复合赋值与解构赋值（数组/对象 pattern）。
+//! 函数：`emit_assignment_expression`。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,6 @@
+//! 调用表达式 emit：普通/原生/`new`/`super` 调用与调用域分发。
+//! 函数：`emit_call_expression`、`emit_call_domain`。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,7 @@
+//! 函数表达式域：箭头/普通函数/类表达式/`new` 表达式的 emit 与分发。
+//! 函数：`emit_arrow_function_expression`、`emit_function_expression`、
+//! `emit_class_expression`、`emit_new_expression`、`emit_function_domain`。
+
 use crate::{CompileCtx, Emitter, ParamSpec};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,5 @@
+//! 标识符表达式 emit：`emit_identifier_expression` 按绑定/builtin/全局解析寄存器。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,6 @@
+//! 字面量表达式 emit：数字/字符串/布尔/null/正则 → 常量池或立即数。
+//! 整数走立即数编码（`is_int_literal`），其余入常量池。
+
 use crate::{is_int_literal, CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,7 @@
+//! 成员访问域：静态/计算/私有字段成员与可选链表达式 emit 及分发。
+//! 函数：`emit_static_member_expression`、`emit_computed_member_expression`、
+//! `emit_private_field_expression`、`emit_chain_expression`、`emit_member_domain`。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,8 @@
+//! 表达式编译域：表达式分发 + sequence/unsupported。
+//!
+//! `emit_expression` 按 `Expression` 变体分发到各子模块；本文件还处理
+//! 序列表达式（逐项求值取末值）与不支持表达式的报错。
+
 use crate::{CompileCtx, Emitter};
 use oxide_parser::Expression;

@@ -1,3 +1,5 @@
+//! 数组字面量 emit：`emit_array_expression` 逐元素求值并建数组（含 holes）。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,5 @@
+//! 对象表达式域：对象/数组字面量子模块与域分发 `emit_object_domain`。
+
 use crate::{CompileCtx, Emitter};
 use oxide_parser::Expression;

@@ -1,3 +1,5 @@
+//! 对象字面量 emit：`emit_object_expression` 逐属性定义（含 getter/setter/展开）。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,7 @@
+//! 运算符域：二元/一元/条件/逻辑/更新/`in` 表达式 emit 与分发。
+//! 逻辑与 `??` 用短路跳转，复合求值利用 `is_side_effect_free` 优化。
+//! 函数：`emit_operator` 及各类 `emit_*_expression`。
+
 use crate::{is_side_effect_free, BinaryOperator, CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,5 @@
+//! 括号表达式 emit：`emit_parenthesized_expression` 透传内层表达式。
+
 use crate::{CompileCtx, Emitter};

 impl Emitter {
@@ -1,3 +1,5 @@
+//! 模板字符串域：普通/标签模板子模块与域分发 `emit_template_domain`。
+
 use crate::{CompileCtx, Emitter};
 use oxide_parser::Expression;

@@ -1,3 +1,5 @@
+//! 标签模板表达式 emit：`emit_tagged_template_expression` 构造 template object 并调用标签函数。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,6 @@
+//! 模板字面量 emit：`emit_template_literal_expression` 生成 TEMPLATE_STR 指令
+//! 拼接字面量段与内插表达式。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,5 @@
+//! `this` 表达式 emit：`emit_this_expression` 解析当前函数的 this 寄存器。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,10 @@
+//! oxide_emit：AST → IR 代码生成层（编译管线中段）。
+//!
+//! 入口 `Emitter::emit_program` 把 parser 产出的 `Program` 编译为分域组合的
+//! `IRFunction`（code/data/bindings/builtins/closures/meta/nested），再由
+//! `oxide_ir::lower` 降为 bytecode。语法按域拆分：`expr/`、`stmt/`、`class/`、
+//! `shared/`；作用域与闭包捕获分析在 emit 前完成，消除符号表时序依赖。
+
 pub mod class;
 pub mod closure;
 pub mod emit;
@@ -1,3 +1,9 @@
+//! emit 前置 pass：builtin 引用预扫描 + 声明预登记。
+//!
+//! 在生成临时寄存器前遍历 AST，把内置全局标识符预先登记到固定寄存器槽
+//! （builtin_reg_map），避免与临时寄存器池冲突；同时预声明函数/var 声明，
+//! 支持提升语义。
+
 use crate::{CompileCtx, Emitter};
 use oxide_parser::{Expression, Statement, VariableDeclarationKind};

@@ -1,3 +1,7 @@
+//! 解构绑定/赋值 emit：数组与对象 pattern 的绑定初始化、rest 收集与解构赋值。
+//! 函数：`emit_bind_target`、`emit_binding_pattern`、`emit_array_binding`、
+//! `emit_object_binding`、`emit_assign_target` 等。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,6 @@
+//! 可选链（`?.`）emit：短路守卫、链式成员访问/调用与逻辑赋值短路测试。
+//! 函数：`emit_chainable_expression`、`emit_optional_guard`、`emit_chain_call` 等。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::{LabelId, Operand};
@@ -1,3 +1,5 @@
+//! 类字段初始化 emit：公有/私有实例字段与私有方法的实例化初始化。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,6 @@
+//! 类属性键/私有名 emit：私有名 id 分配、类字段键寄存器与 undefined 常量。
+//! 函数：`private_name_id`、`emit_private_id_reg`、`emit_class_key_reg` 等。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,5 @@
+//! 跨语法域共享的 emit 辅助：解构绑定、可选链、类字段初始化、类属性键。
+
 pub mod binding;
 pub mod chain;
 pub mod class_field;
@@ -1,3 +1,5 @@
+//! break/continue 语句 emit：解析标签与最近循环的跳转目标。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;

@@ -1,3 +1,5 @@
+//! 表达式语句 emit：`emit_expression_statement` 求值并（按需）丢弃结果。
+
 use crate::{CompileCtx, Emitter};
 use oxide_parser::Statement;

@@ -1,3 +1,5 @@
+//! 标签语句 emit：`emit_labeled_statement` 登记 break/continue 标签作用域。
+
 use crate::{CompileCtx, Emitter};
 use oxide_parser::Statement;

@@ -1,3 +1,5 @@
+//! 基本语句域：表达式语句/return/空语句的分发与子模块聚合。
+
 use crate::{CompileCtx, Emitter};
 use oxide_parser::Statement;

@@ -1,3 +1,5 @@
+//! return 语句 emit：`emit_return_statement` 求值返回值并生成返回指令。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,5 @@
+//! 块语句 emit：`emit_block_statement` 压/弹作用域并顺序编译子语句（含域分发）。
+
 use crate::{CompileCtx, Emitter};
 use oxide_parser::Statement;

@@ -1,3 +1,5 @@
+//! 控制流语句 emit：`if` 条件分支（含 else）与域分发 `emit_control_domain`。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,5 @@
+//! 类声明语句 emit：`emit_class_declaration_statement` 声明类名并初始化类对象。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,5 @@
+//! 函数声明语句 emit：`emit_function_declaration_statement` 创建闭包并绑定函数名。
+
 use crate::{CompileCtx, Emitter, ParamSpec};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,5 @@
+//! 声明语句域：变量/函数/类声明的分发与子模块聚合。
+
 use crate::{CompileCtx, Emitter};
 use oxide_parser::Statement;

@@ -1,3 +1,5 @@
+//! var/let/const 声明语句 emit：声明 + 初始化表达式，处理提升与解构 pattern。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,5 @@
+//! 异常语句域：throw/try 的分发与子模块聚合。
+
 use crate::{CompileCtx, Emitter};
 use oxide_parser::Statement;

@@ -1,3 +1,5 @@
+//! throw 语句 emit：`emit_throw_statement` 求值异常值并生成 THROW。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,5 @@
+//! try/catch/finally 语句 emit：`emit_try_statement` 生成 TRY_BEGIN 与处理入口。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,5 @@
+//! do-while 语句 emit：`emit_do_while_statement` 先执行体后测条件。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_parser::Statement;
@@ -1,3 +1,5 @@
+//! for 语句 emit：`emit_for_statement` 含 init/test/update 三段与循环跳转。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,5 @@
+//! for-in 语句 emit：`emit_for_in_statement` 遍历可枚举属性名。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,5 @@
+//! for-of 语句 emit：`emit_for_of_statement` 迭代器协议遍历。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,5 @@
+//! 迭代语句域：while/do-while/for/for-in/for-of 的分发与子模块聚合。
+
 use crate::{CompileCtx, Emitter};
 use oxide_parser::Statement;

@@ -1,3 +1,5 @@
+//! while 语句 emit：`emit_while_statement` 先测条件后执行体。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_parser::Statement;
@@ -1,3 +1,5 @@
+//! 语句编译域：`emit_statement` 分发到块/控制流/声明/异常/迭代等子模块。
+
 pub mod basic;
 pub mod block;
 pub mod control;
@@ -1,3 +1,5 @@
+//! switch 语句 emit：case 匹配链 + 穿落（fallthrough）与 default，见 `emit_switch_statement`。
+
 use crate::{CompileCtx, Emitter};
 use oxide_ir::inst::Inst;
 use oxide_ir::operand::Operand;
@@ -1,3 +1,9 @@
+//! 标识符合法化 / 作用域符号表。
+//!
+//! 层叠作用域栈：`var` 声明提升到最近函数作用域，`let`/`const` 留在当前块。
+//! 绑定记录寄存器号 + 初始化标志（TDZ 检查）+ const 标志。声明即写入，
+//! `lookup` 在未初始化时报 TDZ 错误。
+
 use std::collections::HashMap;

 use oxide_parser::VariableDeclarationKind;
@@ -19,6 +25,8 @@ pub(crate) struct Binding {
    pub(crate) is_const: bool,
 }

+/// 作用域符号表：名字 → 寄存器号/初始化状态/const 标志。
+/// 首层为全局函数作用域，后续 push 的为块作用域。
 pub struct SymbolTable {
    pub(crate) scopes: Vec<Scope>,
 }
@@ -30,6 +38,7 @@ impl Default for SymbolTable {
 }

 impl SymbolTable {
+    /// 构造符号表：预置一个全局函数作用域。
    pub fn new() -> Self {
        Self {
            scopes: vec![Scope {
@@ -39,6 +48,7 @@ impl SymbolTable {
        }
    }

+    /// 压入新的块作用域（`let`/`const` 限定于此）。
    pub fn push_scope(&mut self) {
        self.scopes.push(Scope {
            bindings: HashMap::new(),
@@ -50,6 +60,7 @@ impl SymbolTable {
        self.scopes.push(Scope { bindings: HashMap::new(), kind });
    }

+    /// 弹出最内层作用域；全局作用域不可弹出。
    pub fn pop_scope(&mut self) {
        if self.scopes.len() > 1 {
            self.scopes.pop();
@@ -65,6 +76,8 @@ impl SymbolTable {
        0
    }

+    /// 声明绑定：`var` 提升到函数作用域，`let`/`const` 落在当前块。
+    /// 初始为未初始化态（TDZ）；重复声明报错。
    pub fn declare(
        &mut self, name: &str, reg: u8, kind: VariableDeclarationKind, is_const: bool,
    ) -> Result<(), String> {
@@ -89,6 +102,7 @@ impl SymbolTable {
        Ok(())
    }

+    /// 从内到外查找已初始化绑定；命中未初始化绑定报 TDZ 错误，未找到报未定义。
    pub fn lookup(&self, name: &str) -> Result<u8, String> {
        for scope in self.scopes.iter().rev() {
            if let Some(b) = scope.bindings.get(name) {
@@ -117,6 +131,7 @@ impl SymbolTable {
        None
    }

+    /// 查找或视为全局：未命中时以 `reg_for_new` 在全局作用域登记并返回（隐式全局）。
    pub fn lookup_or_global(&mut self, name: &str, reg_for_new: u8) -> u8 {
        for scope in self.scopes.iter().rev() {
            if let Some(b) = scope.bindings.get(name) {
@@ -134,6 +149,7 @@ impl SymbolTable {
        reg_for_new
    }

+    /// 返回已初始化绑定是否为 const（用于 const 赋值检查）；未初始化/未找到返回 false。
    pub fn lookup_is_const(&self, name: &str) -> bool {
        for scope in self.scopes.iter().rev() {
            if let Some(b) = scope.bindings.get(name) {
@@ -146,6 +162,7 @@ impl SymbolTable {
        false
    }

+    /// 声明并直接标记为已初始化；绑定已存在时仅补初始化标志（供预声明路径）。
    pub fn declare_initialized(
        &mut self, name: &str, reg: u8, kind: VariableDeclarationKind, is_const: bool,
    ) -> Result<(), String> {
@@ -171,6 +188,7 @@ impl SymbolTable {
        Ok(())
    }

+    /// 在全局作用域预登记绑定（builtin 全局等），不覆盖已存在的同名绑定。
    pub fn pre_register_global(&mut self, name: &str, reg: u8) {
        self.scopes[0].bindings.entry(name.to_string()).or_insert(Binding {
            reg,
@@ -179,6 +197,7 @@ impl SymbolTable {
        });
    }

+    /// 从内到外将同名绑定标记为已初始化（var 提升后初始化阶段使用）。
    pub fn init_var(&mut self, name: &str) {
        for scope in self.scopes.iter_mut().rev() {
            if let Some(b) = scope.bindings.get_mut(name) {
				`@@ -1 +1,2 @@`
				`//! 类编译核心预留模块（当前为空，为后续类相关公共状态预留位置）。`