+ * 赋值语句用于将右侧表达式的值存储到左侧指定的变量中， + * 通常形式为 {@code x = expression}，其中 {@code x} 是目标变量， + * {@code expression} 是用于计算赋值结果的表达式。 + *
+ *+ * 该节点作为语句节点的一种实现，适用于语义分析、类型检查、IR 构建等多个阶段。 + *
* - * @param variable 赋值语句左侧的变量名。 - * @param value 赋值语句右侧的表达式节点，表示要赋给变量的值。 + * @param variable 左值变量名（即赋值目标） + * @param value 表达式右值（即赋值来源） */ public record AssignmentNode(String variable, ExpressionNode value) implements StatementNode { /** - * 返回赋值语句的字符串表示形式，例如 {@code x = y + 1}。 + * 返回赋值语句的字符串形式，便于调试与日志输出。 + *+ * 典型格式形如 {@code x = y + 1}。 + *
* - * @return 表示赋值语句的字符串。 + * @return 表示赋值语句的字符串形式 */ @Override public String toString() { return variable + " = " + value; } -} +} \ No newline at end of file diff --git a/src/main/java/org/jcnc/snow/compiler/parser/ast/BinaryExpressionNode.java b/src/main/java/org/jcnc/snow/compiler/parser/ast/BinaryExpressionNode.java index 9eaa69e..6e49e63 100644 --- a/src/main/java/org/jcnc/snow/compiler/parser/ast/BinaryExpressionNode.java +++ b/src/main/java/org/jcnc/snow/compiler/parser/ast/BinaryExpressionNode.java @@ -3,20 +3,27 @@ package org.jcnc.snow.compiler.parser.ast; import org.jcnc.snow.compiler.parser.ast.base.ExpressionNode; /** - * 表示二元运算表达式的 AST 节点，例如 {@code a + b}。 - * 该节点包含一个左操作数、一个操作符字符串和一个右操作数。 + * {@code BinaryExpressionNode} 表示抽象语法树（AST）中的二元运算表达式节点。 + *+ * 二元表达式通常由两个操作数和一个中间操作符构成，例如 {@code a + b}。 + * 此结构广泛用于数学计算、逻辑判断、字符串拼接等语法结构中。 + *
* - * @param left 表达式左侧的子表达式。 - * @param operator 运算符字符串，例如 "+"、"-"、"*"、"/" 等。 - * @param right 表达式右侧的子表达式。 + * @param left 左操作数（子表达式） + * @param operator 运算符字符串（如 "+", "-", "*", "/" 等） + * @param right 右操作数（子表达式） */ public record BinaryExpressionNode(ExpressionNode left, String operator, ExpressionNode right) implements ExpressionNode { /** - * 返回该二元表达式的字符串表示形式，例如 {@code a + b}。 + * 返回该二元运算表达式的字符串表示形式。 + *+ * 输出格式为：{@code left + " " + operator + " " + right}， + * 适用于调试或打印语法树结构。 + *
* - * @return 表达式的字符串形式。 + * @return 表示该二元表达式的字符串 */ @Override public String toString() { diff --git a/src/main/java/org/jcnc/snow/compiler/parser/ast/CallExpressionNode.java b/src/main/java/org/jcnc/snow/compiler/parser/ast/CallExpressionNode.java index 70ff7ee..c9109a1 100644 --- a/src/main/java/org/jcnc/snow/compiler/parser/ast/CallExpressionNode.java +++ b/src/main/java/org/jcnc/snow/compiler/parser/ast/CallExpressionNode.java @@ -5,18 +5,25 @@ import org.jcnc.snow.compiler.parser.ast.base.ExpressionNode; import java.util.List; /** - * 表示函数调用表达式的 AST 节点，例如 {@code foo(arg1, arg2)}。 - * 包含一个被调用的表达式（callee）和一个参数列表（arguments）。 + * {@code CallExpressionNode} 表示抽象语法树（AST）中的函数调用表达式节点。 + *+ * 函数调用表达式用于表示函数或过程的调用操作， + * 包括被调用对象（callee）以及一组参数表达式（arguments）。 + *
* - * @param callee 被调用的表达式，通常是一个标识符或成员访问表达式。 - * @param arguments 函数调用的参数列表，每个参数都是一个表达式节点。 + * @param callee 被调用的表达式节点，通常为函数标识符或成员访问表达式。 + * @param arguments 参数表达式列表，依照调用顺序排列。 */ public record CallExpressionNode(ExpressionNode callee, List+ * 该格式将输出为类似 {@code foo(a, b, c)} 的形式， + * 便于调试与语法树可视化。 + *
* - * @return 表达式的字符串形式。 + * @return 表示函数调用的字符串表示 */ @Override public String toString() { diff --git a/src/main/java/org/jcnc/snow/compiler/parser/ast/DeclarationNode.java b/src/main/java/org/jcnc/snow/compiler/parser/ast/DeclarationNode.java index 2f0fe53..1819d1f 100644 --- a/src/main/java/org/jcnc/snow/compiler/parser/ast/DeclarationNode.java +++ b/src/main/java/org/jcnc/snow/compiler/parser/ast/DeclarationNode.java @@ -6,20 +6,29 @@ import org.jcnc.snow.compiler.parser.ast.base.StatementNode; import java.util.Optional; /** - * 表示变量声明语句的 AST 节点，例如 {@code int x = 5;}。 - * 该节点包含变量名称、类型，以及可选的初始化表达式。 + * {@code DeclarationNode} 表示抽象语法树（AST）中的变量声明语句节点。 + *+ * 变量声明用于在语法层引入新的标识符及其类型信息， + * 通常格式为 {@code type name = initializer;}，其中初始化表达式可省略。 + *
*/ public class DeclarationNode implements StatementNode { + + /** 声明的变量名称 */ private final String name; + + /** 变量的数据类型（如 "int", "string"） */ private final String type; + + /** 可选的初始化表达式 */ private final Optional+ * 表达式语句通常由一个单独的表达式组成，并以语句形式出现。 + * 例如：{@code foo();}、{@code x = 1;}、{@code print("hello");} 等。 + *
* - * @param expression 表达式内容，通常是函数调用或赋值操作。 + * @param expression 表达式主体，通常为函数调用、赋值、方法链式调用等可求值表达式。 */ public record ExpressionStatementNode(ExpressionNode expression) implements StatementNode { -} +} \ No newline at end of file diff --git a/src/main/java/org/jcnc/snow/compiler/parser/ast/FunctionNode.java b/src/main/java/org/jcnc/snow/compiler/parser/ast/FunctionNode.java index 1f65248..7ab55dd 100644 --- a/src/main/java/org/jcnc/snow/compiler/parser/ast/FunctionNode.java +++ b/src/main/java/org/jcnc/snow/compiler/parser/ast/FunctionNode.java @@ -6,14 +6,18 @@ import org.jcnc.snow.compiler.parser.ast.base.StatementNode; import java.util.List; /** - * 表示函数定义的 AST 节点，包含函数名、参数、返回类型和函数体。 + * {@code FunctionNode} 表示抽象语法树（AST）中的函数定义结构。 + *+ * 函数定义通常包含函数名、形参列表、返回类型以及函数体， + * 在语义分析、类型检查与代码生成等阶段具有核心地位。 * 示例：{@code int add(int a, int b) { return a + b; }} + *
* - * @param name 函数名称。 - * @param parameters 参数列表，每个参数是一个 {@link ParameterNode}。 - * @param returnType 返回值类型，表示函数的返回类型（例如 "int"、"void"）。 - * @param body 函数体，由若干语句组成的列表。 + * @param name 函数名称标识符 + * @param parameters 参数列表，每项为 {@link ParameterNode} 表示一个形参定义 + * @param returnType 函数的返回类型（如 "int"、"void" 等） + * @param body 函数体语句块，由一组 {@link StatementNode} 构成 */ public record FunctionNode(String name, List+ * 该节点用于表示变量名、函数名、字段名等符号引用。 + * 在语义分析中，通常需要将此类节点绑定到其声明位置或符号表项。 + *
* - * @param name 标识符的名称。 + * @param name 标识符的文本名称（如变量名 "x"，函数名 "foo"） */ public record IdentifierNode(String name) implements ExpressionNode { /** - * 返回标识符的字符串表示形式，即其名称。 + * 返回标识符节点的字符串形式，通常为其名称本身。 * - * @return 标识符名称字符串。 + * @return 标识符名称字符串 */ @Override public String toString() { diff --git a/src/main/java/org/jcnc/snow/compiler/parser/ast/IfNode.java b/src/main/java/org/jcnc/snow/compiler/parser/ast/IfNode.java index 5dca2d5..9ac9371 100644 --- a/src/main/java/org/jcnc/snow/compiler/parser/ast/IfNode.java +++ b/src/main/java/org/jcnc/snow/compiler/parser/ast/IfNode.java @@ -6,25 +6,33 @@ import org.jcnc.snow.compiler.parser.ast.base.StatementNode; import java.util.List; /** - * 表示 if 语句的 AST 节点。 - * 包含条件表达式、then 分支语句列表，以及可选的 else 分支。 - * 示例： + * {@code IfNode} 表示抽象语法树（AST）中的条件语句结构（if-else）。 + *+ * 该节点包含一个条件表达式（condition）、一个 then 分支语句列表， + * 以及一个可选的 else 分支语句列表。 + *
+ *+ * 条件表达式为布尔类型，决定是否执行 then 分支。 + * 若 condition 为假，则执行 else 分支（如果提供）。 + *
+ *+ * 示例语法结构： + *
*{@code
- * if (x > 0) {
+ * if (x > 0) {
* print("Positive");
- * } else {
+ * } else {
* print("Negative");
- * }
* }
* }
*
- * @param condition 条件表达式，控制是否进入 thenBranch。
- * @param thenBranch 条件为真时执行的语句列表。
- * @param elseBranch 条件为假时执行的语句列表（可为空）。
+ * @param condition 控制分支执行的条件表达式
+ * @param thenBranch 条件为 true 时执行的语句块
+ * @param elseBranch 条件为 false 时执行的语句块（可为空）
*/
public record IfNode(
ExpressionNode condition,
List+ * import 语句用于引入外部模块或库文件，其语法形式一般为： + * {@code import my.module;} + *
+ *+ * 本节点仅存储导入目标模块的名称，不包含路径解析或绑定逻辑， + * 这些通常由语义分析器或模块加载器处理。 + *
* - * @param moduleName 被导入的模块名称。 + * @param moduleName 被导入的模块名称，通常为点分层次结构（如 "core.utils"） */ public record ImportNode(String moduleName) implements Node { -} +} \ No newline at end of file diff --git a/src/main/java/org/jcnc/snow/compiler/parser/ast/LoopNode.java b/src/main/java/org/jcnc/snow/compiler/parser/ast/LoopNode.java index 0200aa6..7821ae4 100644 --- a/src/main/java/org/jcnc/snow/compiler/parser/ast/LoopNode.java +++ b/src/main/java/org/jcnc/snow/compiler/parser/ast/LoopNode.java @@ -6,20 +6,18 @@ import org.jcnc.snow.compiler.parser.ast.base.StatementNode; import java.util.List; /** - * 表示循环语句（loop）的 AST 节点，结构类似于传统的 for 循环。 - * 包含初始化语句、循环条件、更新语句和循环体。 - * 示例： - * {@code - * for (int i = 0; i < 10; i++) { - * print(i); - * } - * } + * {@code LoopNode} 表示抽象语法树（AST）中的循环语句结构。 + *+ * 该节点建模了类似传统 {@code for} 循环的控制结构， + * 包含初始化语句、循环条件、更新语句及循环体。 + * 每一部分均对应为 AST 中的子节点，便于进一步语义分析与代码生成。 + *
* - * @param initializer 循环开始前执行的初始化语句。 - * @param condition 每次迭代前都会评估的条件表达式。 - * @param update 每次迭代结束时执行的更新语句。 - * @param body 循环体内的语句列表。 + * @param initializer 在循环开始前执行的初始化语句 + * @param condition 每次迭代前评估的条件表达式，控制循环是否继续 + * @param update 每轮迭代完成后执行的更新语句 + * @param body 循环体语句列表，表示循环主体执行逻辑 */ public record LoopNode(StatementNode initializer, ExpressionNode condition, StatementNode update, List+ * 用于表示对象字段或方法的访问操作，语法形式如 {@code object.member}。 + * 成员访问常见于结构体、模块、对象导入等上下文中，是表达式链中常见的构件之一。 + *
* - * @param object 表达式左侧的对象部分，通常是一个标识符或更复杂的表达式。 - * @param member 成员名称，表示要访问的字段或方法。 + * @param object 左侧对象表达式，表示成员所属的作用域或容器 + * @param member 要访问的成员名称（字段名或方法名） */ public record MemberExpressionNode(ExpressionNode object, String member) implements ExpressionNode { /** - * 返回成员访问表达式的字符串表示形式，例如 {@code obj.prop}。 + * 返回成员访问表达式的字符串形式。 + *+ * 输出格式为 {@code object.member}，用于调试或语法树可视化。 + *
* - * @return 成员访问表达式的字符串形式。 + * @return 成员访问表达式的字符串形式 */ @Override public String toString() { return object + "." + member; } -} +} \ No newline at end of file diff --git a/src/main/java/org/jcnc/snow/compiler/parser/ast/ModuleNode.java b/src/main/java/org/jcnc/snow/compiler/parser/ast/ModuleNode.java index 47dd980..564402a 100644 --- a/src/main/java/org/jcnc/snow/compiler/parser/ast/ModuleNode.java +++ b/src/main/java/org/jcnc/snow/compiler/parser/ast/ModuleNode.java @@ -8,12 +8,6 @@ import java.util.StringJoiner; /** * 表示模块定义的 AST 节点。 * 一个模块通常由模块名、导入语句列表和函数定义列表组成。 - * 示例结构： - * {@code - * module my.module { - * import other.module; - * fun foo() { ... } - * } * } * * @param name 模块名称。 diff --git a/src/main/java/org/jcnc/snow/compiler/parser/ast/NumberLiteralNode.java b/src/main/java/org/jcnc/snow/compiler/parser/ast/NumberLiteralNode.java index 54ba424..f30f526 100644 --- a/src/main/java/org/jcnc/snow/compiler/parser/ast/NumberLiteralNode.java +++ b/src/main/java/org/jcnc/snow/compiler/parser/ast/NumberLiteralNode.java @@ -3,17 +3,21 @@ package org.jcnc.snow.compiler.parser.ast; import org.jcnc.snow.compiler.parser.ast.base.ExpressionNode; /** - * 表示数字字面量的表达式节点，例如 {@code 42} 或 {@code 3.14}。 - * 该节点直接保存字面量的字符串形式，便于统一处理整数和浮点数。 + * {@code NumberLiteralNode} 表示抽象语法树（AST）中的数字字面量表达式节点。 + *+ * 用于表示源代码中的数值常量，如整数 {@code 42} 或浮点数 {@code 3.14}。 + * 为了兼容不同数值格式，本节点以字符串形式存储原始值， + * 在语义分析或类型推导阶段再行解析为具体数值类型。 + *
* - * @param value 数字的字符串表示形式。 + * @param value 数字字面量的原始字符串表示 */ public record NumberLiteralNode(String value) implements ExpressionNode { /** * 返回数字字面量的字符串形式。 * - * @return 字面量的原始字符串值。 + * @return 字面量原始字符串值（例如 "42" 或 "3.14"） */ @Override public String toString() { diff --git a/src/main/java/org/jcnc/snow/compiler/parser/ast/ParameterNode.java b/src/main/java/org/jcnc/snow/compiler/parser/ast/ParameterNode.java index 94ddc50..91e93aa 100644 --- a/src/main/java/org/jcnc/snow/compiler/parser/ast/ParameterNode.java +++ b/src/main/java/org/jcnc/snow/compiler/parser/ast/ParameterNode.java @@ -3,21 +3,27 @@ package org.jcnc.snow.compiler.parser.ast; import org.jcnc.snow.compiler.parser.ast.base.Node; /** - * 表示函数参数的 AST 节点，包含参数名称和类型。 - * 示例：在 {@code int add(int a, int b)} 中，{@code a:int} 和 {@code b:int} 都是参数节点。 + * {@code ParameterNode} 表示抽象语法树（AST）中的函数参数定义节点。 + *+ * 每个参数节点包含参数的名称和类型信息， + * 用于构成函数签名并参与类型检查与函数调用匹配。 + *
* - * @param name 参数名称。 - * @param type 参数类型（例如 "int"、"string"）。 + * @param name 参数名称标识符 + * @param type 参数类型字符串（如 "int"、"string"） */ public record ParameterNode(String name, String type) implements Node { /** - * 返回参数的字符串表示形式，格式为 {@code name:type}，如 {@code num:int}。 + * 返回参数的字符串形式，格式为 {@code name:type}。 + *+ * 用于调试输出或构建函数签名描述。 + *
* - * @return 参数的字符串表示，适用于调试或打印参数列表。 + * @return 参数的字符串形式（如 {@code count:int}） */ @Override public String toString() { return name + ":" + type; } -} +} \ No newline at end of file diff --git a/src/main/java/org/jcnc/snow/compiler/parser/ast/ReturnNode.java b/src/main/java/org/jcnc/snow/compiler/parser/ast/ReturnNode.java index 7357d51..28143dd 100644 --- a/src/main/java/org/jcnc/snow/compiler/parser/ast/ReturnNode.java +++ b/src/main/java/org/jcnc/snow/compiler/parser/ast/ReturnNode.java @@ -6,31 +6,38 @@ import org.jcnc.snow.compiler.parser.ast.base.StatementNode; import java.util.Optional; /** - * 表示 return 语句的 AST 节点，支持可选的返回值表达式。 + * {@code ReturnNode} 表示抽象语法树（AST）中的 return 语句节点。 + *+ * return 语句用于从当前函数中返回控制权，并可携带一个可选的返回值表达式。 + *
+ ** 示例： *
+ * 用于表示源代码中出现的字符串常量，如 {@code "hello"}、{@code "abc123"} 等。 + * 节点内部仅保存不带引号的字符串内容，便于后续语义处理或编码。 + *
* - * @param value 字符串内容，不包括两端引号。 + * @param value 字符串常量的内容，原始值中不包含双引号 */ public record StringLiteralNode(String value) implements ExpressionNode { /** - * 返回带引号的字符串表示形式，适用于调试和打印。 - * 例如：如果 {@code value = Result:}，则 {@code toString()} 返回 {@code "Result:"}。 + * 返回字符串字面量的带引号表示，适用于语法树调试或文本输出。 + *+ * 例如，当 {@code value = Result:} 时，返回 {@code "Result:"}。 + *
* - * @return 添加双引号后的字符串字面量。 + * @return 字符串字面量的完整表示形式（带双引号） */ @Override public String toString() { return "\"" + value + "\""; } -} +} \ No newline at end of file diff --git a/src/main/java/org/jcnc/snow/compiler/parser/ast/base/ExpressionNode.java b/src/main/java/org/jcnc/snow/compiler/parser/ast/base/ExpressionNode.java index b48c836..e8db645 100644 --- a/src/main/java/org/jcnc/snow/compiler/parser/ast/base/ExpressionNode.java +++ b/src/main/java/org/jcnc/snow/compiler/parser/ast/base/ExpressionNode.java @@ -1,8 +1,14 @@ package org.jcnc.snow.compiler.parser.ast.base; /** - * 表示抽象语法树中的表达式节点类型。 - * 所有具体的表达式（如常量、变量、运算、函数调用等）都应实现该接口。 - * 这是一个标记接口（marker interface），用于统一处理所有表达式节点。 + * {@code ExpressionNode} 表示抽象语法树（AST）中所有表达式类型节点的统一接口。 + *+ * 作为标记接口（Marker Interface），该接口用于区分表达式与其他语法结构， + * 不定义具体方法，其子类型通常表示可参与求值运算的结构， + * 如常量表达式、变量引用、函数调用、算术运算等。 + *
+ *+ * 所有实现此接口的节点可参与表达式求值、语义分析、类型检查与中间代码生成等处理流程。 + *
*/ -public interface ExpressionNode extends Node {} +public interface ExpressionNode extends Node {} \ No newline at end of file diff --git a/src/main/java/org/jcnc/snow/compiler/parser/ast/base/Node.java b/src/main/java/org/jcnc/snow/compiler/parser/ast/base/Node.java index 42452d9..8c7a8b9 100644 --- a/src/main/java/org/jcnc/snow/compiler/parser/ast/base/Node.java +++ b/src/main/java/org/jcnc/snow/compiler/parser/ast/base/Node.java @@ -1,8 +1,18 @@ package org.jcnc.snow.compiler.parser.ast.base; /** - * 所有抽象语法树（AST）节点的标记接口。 - * 所有具体的语法节点类型（如表达式、语句、模块、函数等）都应实现该接口。 - * 该接口本身不定义任何方法，仅用于类型标识和统一处理。 + * {@code Node} 是抽象语法树（AST）中所有语法节点的统一根接口。 + *+ * 作为标记接口（Marker Interface），该接口不定义任何方法， + * 主要用于统一标识并组织 AST 体系中的各种语法构件节点，包括： + *
+ *+ * 所有 AST 处理逻辑（如遍历、分析、代码生成）均可基于该接口实现统一调度和类型判定。 + *
*/ public interface Node {} diff --git a/src/main/java/org/jcnc/snow/compiler/parser/ast/base/StatementNode.java b/src/main/java/org/jcnc/snow/compiler/parser/ast/base/StatementNode.java index cae804c..b4db2cb 100644 --- a/src/main/java/org/jcnc/snow/compiler/parser/ast/base/StatementNode.java +++ b/src/main/java/org/jcnc/snow/compiler/parser/ast/base/StatementNode.java @@ -1,8 +1,11 @@ package org.jcnc.snow.compiler.parser.ast.base; /** - * 表示语法树中的语句节点类型。 - * 所有语句类（如声明、赋值、if、loop、return 等）都应实现该接口。 - * 这是一个标记接口（marker interface），用于统一处理所有语句节点。 + * {@code StatementNode} 表示抽象语法树（AST）中所有语句结构的统一接口。 + *+ * 该接口为标记接口（Marker Interface），用于识别和区分语句类节点， + * 包括但不限于变量声明、赋值语句、控制结构（如 if、loop）、返回语句等。 + * 实现此接口的类应表示程序在运行时执行的具体语法行为。 + *
*/ public interface StatementNode extends Node {}