完善注释

src/main/java/org/jcnc/snow/compiler/semantic/BuiltinType.java

@@ -1,18 +1,54 @@
 package org.jcnc.snow.compiler.semantic;
 
 /**
- * 内置基础类型枚举：int, string, void。
+ * 内置基础类型枚举。
- * 其中 int 也可用于表示真假值。
+ * <p>
+ * 本枚举定义了编译器中最基本的三种内置类型：
+ * <ul>
+ *     <li>INT：整数类型，同时也可用于表示布尔值（真假值）。</li>
+ *     <li>STRING：字符串类型。</li>
+ *     <li>VOID：无返回值类型，通常用于函数无返回值的情况。</li>
+ * </ul>
+ * <p>
+ * 实现了 Type 接口，提供了基本的类型兼容性判断和字符串表示方法。
  */
 public enum BuiltinType implements Type {
-    INT, STRING, VOID;
+    /**
+     * 整数类型，也可用于布尔值。
+     */
+    INT,
 
+    /**
+     * 字符串类型。
+     */
+    STRING,
+
+    /**
+     * 空类型，用于表示无返回值的情况。
+     */
+    VOID;
+
+    /**
+     * 判断当前类型是否与另一个类型兼容。
+     * <p>
+     * 兼容的条件是两个类型必须完全相同（引用相等）。
+     *
+     * @param other 另一个需要检查兼容性的类型
+     * @return 如果类型完全相同则返回 true，否则返回 false
+     */
     @Override
     public boolean isCompatible(Type other) {
-        // 完全相同类型才兼容
+        // 只有当两个类型对象是同一个实例时才认为兼容
         return this == other;
     }
 
+    /**
+     * 将类型转换为小写字符串形式。
+     * <p>
+     * 例如：INT 会转换为 "int"。
+     *
+     * @return 当前类型的小写字符串表示
+     */
     @Override
     public String toString() {
         return name().toLowerCase();

src/main/java/org/jcnc/snow/compiler/semantic/FunctionType.java

@@ -1,16 +1,45 @@
 package org.jcnc.snow.compiler.semantic;
 
 import java.util.List;
+import java.util.Objects;
 
 /**
- * 表示函数类型，包含参数类型列表和返回类型。
+ * 表示函数类型。
+ * <p>
+ * 一个函数类型由参数类型列表和返回类型共同确定。
+ * 例如：一个接受两个 int 参数并返回 string 的函数，其类型描述为 (int, int) -> string。
+ * <p>
+ * 本类是一个 Java record，自动生成基本的构造方法、访问器、equals 和 hashCode 方法，
+ * 并实现了 {@link Type} 接口，支持类型兼容性检查和字符串表示。
  */
 public record FunctionType(List<Type> paramTypes, Type returnType) implements Type {
+    /**
+     * 构造函数类型。
+     * <p>
+     * {@link java.util.Collections#unmodifiableList(List)} 包装成不可变列表，
+     * 保证函数类型对象本身的安全性和不可变性。
+     *
+     * @param paramTypes 参数类型列表
+     * @param returnType 返回类型
+     */
     public FunctionType(List<Type> paramTypes, Type returnType) {
         this.paramTypes = List.copyOf(paramTypes);
         this.returnType = returnType;
     }
 
+    /**
+     * 判断当前函数类型是否与另一个类型兼容。
+     * <p>
+     * 兼容条件为：
+     * <ul>
+     *     <li>另一类型也是 FunctionType。</li>
+     *     <li>返回类型兼容。</li>
+     *     <li>参数类型列表完全相等（顺序和值一致）。</li>
+     * </ul>
+     *
+     * @param other 需要检查兼容性的另一个类型
+     * @return 如果兼容返回 true，否则返回 false
+     */
     @Override
     public boolean isCompatible(Type other) {
         if (!(other instanceof FunctionType)) return false;
@@ -19,11 +48,30 @@ public record FunctionType(List<Type> paramTypes, Type returnType) implements Ty
                 && paramTypes.equals(o.paramTypes);
     }
 
+    /**
+     * 返回函数类型的字符串表示。
+     * <p>
+     * 格式为："(参数类型列表) -> 返回类型"，例如：<code>(int, string) -> void</code>。
+     *
+     * @return 函数类型的字符串表示
+     */
     @Override
     public String toString() {
         return "(" + paramTypes + ") -> " + returnType;
     }
 
+    /**
+     * 判断当前函数类型是否与另一个对象相等。
+     * <p>
+     * 相等条件为：
+     * <ul>
+     *     <li>对象引用相同，或</li>
+     *     <li>对象是 FunctionType 类型，且参数类型列表和返回类型都相等。</li>
+     * </ul>
+     *
+     * @param obj 另一个对象
+     * @return 如果相等返回 true，否则返回 false
+     */
     @Override
     public boolean equals(Object obj) {
         if (this == obj) return true;
@@ -33,4 +81,15 @@ public record FunctionType(List<Type> paramTypes, Type returnType) implements Ty
                 && paramTypes.equals(o.paramTypes);
     }
 
+    /**
+     * 返回函数类型的哈希码。
+     * <p>
+     * 计算规则是基于参数类型列表和返回类型，保证与 {@link #equals(Object)} 方法一致。
+     *
+     * @return 函数类型的哈希值
+     */
+    @Override
+    public int hashCode() {
+        return Objects.hash(paramTypes, returnType);
+    }
 }

src/main/java/org/jcnc/snow/compiler/semantic/ModuleInfo.java

@@ -6,19 +6,38 @@ import java.util.Map;
 import java.util.Set;
 
 /**
- * 保存模块级别信息，包括模块名、导入列表和函数签名。
+ * 保存模块级别的信息。
+ * <p>
+ * 模块信息包括：
+ * <ul>
+ *     <li>模块名（唯一标识一个模块）。</li>
+ *     <li>导入的其他模块名称集合。</li>
+ *     <li>模块中定义的函数签名映射（函数名到 {@link FunctionType} 的对应关系）。</li>
+ * </ul>
+ * <p>
+ * 主要用于语义分析阶段，帮助管理模块之间的依赖关系和函数声明信息。
  */
 public class ModuleInfo {
+    /** 模块名称 */
     private final String name;
+    /** 导入的模块名称集合 */
     private final Set<String> imports = new HashSet<>();
+    /** 模块中定义的函数映射表：函数名 -> 函数类型 */
     private final Map<String, FunctionType> functions = new HashMap<>();
 
+    /**
+     * 构造一个新的模块信息对象。
+     *
+     * @param name 模块名称
+     */
     public ModuleInfo(String name) {
         this.name = name;
     }
 
     /**
      * 获取模块名称。
+     *
+     * @return 模块名称
      */
     public String getName() {
         return name;
@@ -26,13 +45,22 @@ public class ModuleInfo {
 
     /**
      * 获取导入的模块名称集合。
+     * <p>
+     * 返回的是内部集合的直接引用，可以通过它进行增删操作。
+     *
+     * @return 导入模块名称的集合
      */
     public Set<String> getImports() {
         return imports;
     }
 
     /**
-     * 获取模块中函数签名映射：函数名 -> 函数类型。
+     * 获取模块中定义的函数映射表。
+     * <p>
+     * 返回的是函数名到函数类型 {@link FunctionType} 的映射表。
+     * 返回的是内部映射的直接引用，可以通过它进行增删操作。
+     *
+     * @return 函数映射表
      */
     public Map<String, FunctionType> getFunctions() {
         return functions;