vars = new HashMap<>();
/**
- * 当前作用域所属的 IRFunction，用于分配新的寄存器。
+ * 当前作用域所绑定的 IRFunction 对象，用于申请新的虚拟寄存器。
*/
private IRFunction fn;
/**
- * 关联一个 IRFunction 到当前作用域，用于后续寄存器分配。
+ * 将指定的 IRFunction 关联到当前作用域，以便后续声明变量时能够
+ * 调用该函数的 newRegister() 方法生成新的寄存器。
*
- * @param fn 要绑定的 IRFunction 实例
+ * @param fn 要绑定到本作用域的 IRFunction 实例
*/
void attachFunction(IRFunction fn) {
this.fn = fn;
}
/**
- * 声明一个新变量，并为其分配一个新的虚拟寄存器。
+ * 在当前作用域中声明一个新变量，并为其分配一个新的虚拟寄存器。
+ * 调用绑定的 IRFunction.newRegister() 生成寄存器后保存到映射表中。
*
- * @param name 变量名
+ * @param name 变量名称，作为映射键使用
*/
void declare(String name) {
IRVirtualRegister reg = fn.newRegister();
@@ -46,30 +51,33 @@ final class IRBuilderScope {
}
/**
- * 声明或导入一个已有寄存器到当前作用域。
+ * 在当前作用域中声明或导入一个已有的虚拟寄存器，并将其与指定变量名绑定。
+ * 该方法可用于将外部或前一作用域的寄存器导入到本作用域。
*
- * @param name 变量名
- * @param reg 对应的虚拟寄存器
+ * @param name 变量名称，作为映射键使用
+ * @param reg 要绑定到该名称的 IRVirtualRegister 实例
*/
void declare(String name, IRVirtualRegister reg) {
vars.put(name, reg);
}
/**
- * 更新已声明变量对应的虚拟寄存器。
+ * 更新已存在变量的虚拟寄存器绑定关系。若变量已声明，则替换其对应的寄存器；
+ * 若尚未声明，则等同于声明新变量。
*
- * @param name 变量名
- * @param reg 新的虚拟寄存器
+ * @param name 变量名称，作为映射键使用
+ * @param reg 新的 IRVirtualRegister 实例，用于替换旧绑定
*/
void put(String name, IRVirtualRegister reg) {
vars.put(name, reg);
}
/**
- * 根据变量名查找其对应的虚拟寄存器。
+ * 根据变量名称在当前作用域中查找对应的虚拟寄存器。
*
- * @param name 变量名
- * @return 对应的 IRVirtualRegister，若未声明则返回 null
+ * @param name 需要查询的变量名称
+ * @return 如果该名称已绑定寄存器，则返回对应的 IRVirtualRegister；
+ * 如果未声明，则返回 null
*/
IRVirtualRegister lookup(String name) {
return vars.get(name);
diff --git a/src/main/java/org/jcnc/snow/compiler/ir/builder/IRContext.java b/src/main/java/org/jcnc/snow/compiler/ir/builder/IRContext.java
index 3d5edc4..601b73e 100644
--- a/src/main/java/org/jcnc/snow/compiler/ir/builder/IRContext.java
+++ b/src/main/java/org/jcnc/snow/compiler/ir/builder/IRContext.java
@@ -5,71 +5,74 @@ import org.jcnc.snow.compiler.ir.core.IRInstruction;
import org.jcnc.snow.compiler.ir.value.IRVirtualRegister;
/**
- * IRContext 封装了当前函数的 IRFunction 实例和作用域管理（IRBuilderScope），
- * 并提供分配寄存器和添加 IR 指令的便利方法。
+ * IRContext 类负责封装当前正在构建的 IRFunction 实例
+ * 以及与之配套的作用域管理（IRBuilderScope），
+ * 并简化虚拟寄存器分配与 IR 指令添加操作。
*
- * 主要功能：
+ *
本类提供以下核心功能：
*
- * - 持有正在构建的 IRFunction 对象；
- * - 管理变量名到虚拟寄存器的映射作用域；
- * - 分配新的虚拟寄存器；
- * - 将生成的 IRInstruction 自动添加到 IRFunction。
+ * - 持有并操作当前 IRFunction 对象；
+ * - 管理变量名与虚拟寄存器的映射关系；
+ * - 分配新的虚拟寄存器实例；
+ * - 将生成的 IRInstruction 自动添加到 IRFunction 中；
*
*/
public class IRContext {
/**
- * 正在构建的 IRFunction 对象
+ * 当前正在构建的 IRFunction 对象，所有指令将添加至此
*/
private final IRFunction function;
- /**
- * 管理变量和寄存器映射的作用域
- */
- private final IRBuilderScope IRBuilderScope;
/**
- * 构造 IRContext，并绑定要构建的 IRFunction。
+ * 用于管理当前函数作用域内变量与虚拟寄存器的映射
+ */
+ private final IRBuilderScope scope;
+
+ /**
+ * 构造一个新的 IRContext，并将指定的 IRFunction 与作用域关联。
*
- * @param function 要构建的 IRFunction 对象
+ * @param function 要构建的 IRFunction 实例
*/
public IRContext(IRFunction function) {
this.function = function;
- this.IRBuilderScope = new IRBuilderScope();
- // 将 IRFunction 与作用域关联，以便指令生成时使用
- this.IRBuilderScope.attachFunction(function);
+ this.scope = new IRBuilderScope();
+ // 关联作用域与 IRFunction，以便在声明变量时申请寄存器
+ this.scope.attachFunction(function);
}
/**
- * 获取当前 IRFunction。
+ * 获取当前正在构建的 IRFunction 对象。
*
- * @return 当前正在构建的 IRFunction 对象
+ * @return 当前 IRFunction 实例
*/
public IRFunction getFunction() {
return function;
}
/**
- * 获取当前作用域，用于变量声明和查找。
+ * 获取当前函数的变量与寄存器映射作用域。
*
- * @return 作用域对象 IRBuilderScope
+ * 包内可见：仅限 builder 包内部使用。
+ *
+ * @return IRBuilderScope 实例
*/
- /* 包内可见：仅在 builder 包内部使用 IRBuilderScope */
IRBuilderScope getScope() {
- return IRBuilderScope;
+ return scope;
}
/**
- * 分配一个新的虚拟寄存器。
+ * 为当前函数分配一个新的虚拟寄存器。
*
- * @return 新分配的 IRVirtualRegister 对象
+ * @return 分配到的 IRVirtualRegister 对象
*/
public IRVirtualRegister newRegister() {
return function.newRegister();
}
/**
- * 将给定的 IRInstruction 添加到 IRFunction 中。
+ * 将指定的 IRInstruction 添加到当前 IRFunction 的指令列表中。
*
- * @param instr 要添加的 IR 指令
+ * @param instr 要添加的 IRInstruction 实例
*/
public void addInstruction(IRInstruction instr) {
function.add(instr);
diff --git a/src/main/java/org/jcnc/snow/compiler/ir/builder/IRProgramBuilder.java b/src/main/java/org/jcnc/snow/compiler/ir/builder/IRProgramBuilder.java
index 27a9267..a1168ec 100644
--- a/src/main/java/org/jcnc/snow/compiler/ir/builder/IRProgramBuilder.java
+++ b/src/main/java/org/jcnc/snow/compiler/ir/builder/IRProgramBuilder.java
@@ -10,66 +10,70 @@ import org.jcnc.snow.compiler.parser.ast.base.StatementNode;
import java.util.List;
/**
- * IRProgramBuilder 用于将 AST 根节点列表构建为 IRProgram。
+ * 本类负责将解析生成的 AST 根节点列表转换为可执行的 IRProgram。
*
- *
功能：
+ *
主要职责：
*
- * - 遍历顶层节点，识别模块、函数或顶层语句；
- * - 将函数节点转换为 IRFunction 并添加到 IRProgram；
- * - 对脚本式顶层语句自动包装为特殊的 _start 函数。
+ * - 遍历输入的顶层节点，识别 ModuleNode、FunctionNode 及脚本式顶层 StatementNode；
+ * - 对 ModuleNode 中的所有函数节点调用 FunctionBuilder 构建 IRFunction 并添加至 IRProgram；
+ * - 对单独的 FunctionNode 节点直接构建并纳入 IRProgram；
+ * - 对顶层脚本式 StatementNode 自动封装为名称固定的“_start”函数，再行构建并纳入 IRProgram；
+ * - 对不支持的节点类型抛出 IllegalStateException，以确保编译流程严谨。
*
*/
public final class IRProgramBuilder {
/**
- * 构建一个完整的 IRProgram。
+ * 构建完整的 IRProgram 实例。
*
- * @param roots AST 根节点列表，可包含 ModuleNode、FunctionNode 或 StatementNode
- * @return 构建好的 IRProgram 实例
- * @throws IllegalStateException 当遇到不支持的顶层节点时抛出
+ * @param roots 含 ModuleNode、FunctionNode 或 StatementNode 的顶层 AST 根节点列表
+ * @return 包含所有转换后 IRFunction 的 IRProgram 对象
+ * @throws IllegalStateException 遇到不支持的顶层节点类型时抛出
*/
public IRProgram buildProgram(List roots) {
IRProgram irProgram = new IRProgram();
for (Node node : roots) {
switch (node) {
case ModuleNode moduleNode ->
- // 模块节点：将模块内的所有函数加入程序
+ // 模块节点：批量构建并添加模块内所有函数
moduleNode.functions().forEach(f -> irProgram.add(buildFunction(f)));
- case FunctionNode f ->
- // 顶层函数节点
- irProgram.add(buildFunction(f));
+ case FunctionNode functionNode ->
+ // 顶层函数节点：直接构建并添加
+ irProgram.add(buildFunction(functionNode));
case StatementNode statementNode ->
- // 顶层脚本语句，包装为 _start 函数
+ // 脚本式顶层语句：封装为“_start”函数后构建并添加
irProgram.add(buildFunction(wrapTopLevel(statementNode)));
- case null, default -> throw new IllegalStateException("Unsupported top-level node: " + node);
+ default ->
+ // 严格校验节点类型，遇不支持者立即失败
+ throw new IllegalStateException("Unsupported top-level node: " + node);
}
}
return irProgram;
}
/**
- * 使用 FunctionBuilder 构建 IRFunction。
+ * 利用 FunctionBuilder 将 FunctionNode 转换为 IRFunction。
*
- * @param functionNode AST 中的 FunctionNode
- * @return 构建完成的 IRFunction
+ * @param functionNode 待构建的 AST FunctionNode
+ * @return 构建完成的 IRFunction 实例
*/
private IRFunction buildFunction(FunctionNode functionNode) {
return new FunctionBuilder().build(functionNode);
}
/**
- * 将顶层脚本式语句包装为名为 _start 的 FunctionNode。
+ * 将单个脚本式顶层 StatementNode 封装为名称固定的“_start”函数节点。
*
- * 构造参数说明：
+ *
封装规则：
*
- * - 函数名固定为 "_start"；
- * - 返回类型设为 null，表示类型推断或默认处理；
+ * - 函数名固定为“_start”；
+ * - 返回类型设为 null，由后续流程处理；
* - 参数列表为空；
- * - 函数体仅包含给定的单条语句。
+ * - 函数主体仅包含传入的单条语句。
*
*
- * @param stmt 要包装的顶层语句节点
- * @return 新建的 FunctionNode
+ * @param stmt 待封装的顶层脚本语句节点
+ * @return 生成的 FunctionNode，用于后续 IRFunction 构建
*/
private FunctionNode wrapTopLevel(StatementNode stmt) {
return new FunctionNode("_start", null, String.valueOf(List.of()), List.of(stmt));
diff --git a/src/main/java/org/jcnc/snow/compiler/ir/builder/InstructionFactory.java b/src/main/java/org/jcnc/snow/compiler/ir/builder/InstructionFactory.java
index f303f12..8e4611d 100644
--- a/src/main/java/org/jcnc/snow/compiler/ir/builder/InstructionFactory.java
+++ b/src/main/java/org/jcnc/snow/compiler/ir/builder/InstructionFactory.java
@@ -10,7 +10,7 @@ import org.jcnc.snow.compiler.ir.value.IRVirtualRegister;
/**
* InstructionFactory 统一管理 IR 指令的创建，并自动将生成的指令添加到上下文中。
*
- * 提供的功能包括：
+ *
主要功能包括：
*
* - 生成加载常量指令（LoadConstInstruction）；
* - 生成二元运算指令（BinaryOperationInstruction）；