增加注释

src/main/java/org/jcnc/snow/compiler/lexer/token/Token.java

@@ -1,28 +1,28 @@
 package org.jcnc.snow.compiler.lexer.token;
 
 /**
- * 表示词法分析过程中生成的一个 Token 实例，包含其类型、清洗后的词素、原始片段及在源文件中的位置信息。
+ * {@code Token} 表示词法分析过程中生成的最小语法单元，
+ * 包含类型信息、词素内容、源代码中对应的原始文本片段以及精确的位置信息。
+ * <p>
+ * 一个 Token 通常对应源代码中一个具有语义意义的片段，如关键字、标识符、常量、运算符等。
+ * 区分 lexeme（清洗后的词素）与 raw（原始片段）是为了支持如带引号的字符串、注释等需要保留原始形式的元素。
+ * </p>
  */
 public class Token {
-    /**
+
-     * Token 的类型，如 KEYWORD、IDENTIFIER、TYPE 等。
+    /** Token 的类型，如 KEYWORD、IDENTIFIER、TYPE 等。 */
-     */
     private final TokenType type;
-    /**
+
-     * 清洗后的词素内容，例如去掉引号的字符串正文或注释正文。
+    /** 清洗后的词素内容，例如去掉引号的字符串正文或注释正文。 */
-     */
     private final String lexeme;
-    /**
+
-     * 源代码中对应的原始片段，可能包含引号或注释符号等。
+    /** 源代码中对应的原始片段，可能包含引号、注释符号等。 */
-     */
     private final String raw;
-    /**
+
-     * Token 在源文件中的行号，从 1 开始计算。
+    /** Token 在源文件中的行号，从 1 开始计数。 */
-     */
     private final int line;
-    /**
+
-     * Token 在源文件行中的列号，从 1 开始计算。
+    /** Token 在源文件行中的列号，从 1 开始计数。 */
-     */
     private final int col;
 
     /**
@@ -31,8 +31,8 @@ public class Token {
      * @param type   Token 类型
      * @param lexeme 清洗后的词素内容
      * @param raw    源代码中的原始片段
-     * @param line   所在源文件的行号，从 1 开始
+     * @param line   所在源文件的行号（从 1 开始）
-     * @param col    所在源文件行的列号，从 1 开始
+     * @param col    所在源文件行的列号（从 1 开始）
      */
     public Token(TokenType type, String lexeme, String raw, int line, int col) {
         this.type = type;
@@ -43,77 +43,65 @@ public class Token {
     }
 
     /**
-     * 构造一个简单的 Token 实例，清洗后的词素与原始片段相同。
+     * 构造一个简化形式的 Token，词素与原始片段一致。
-     * <p>适用于非注释、非字符串等无需区分 raw 与 lexeme 的场景。</p>
+     * <p>
+     * 适用于标识符、关键字、符号等不需要区分原始与清洗内容的 Token。
+     * </p>
      *
      * @param type   Token 类型
-     * @param lexeme 词素内容（即原始片段）
+     * @param lexeme Token 内容（同时作为原始片段）
-     * @param line   所在源文件的行号，从 1 开始
+     * @param line   行号
-     * @param col    所在源文件行的列号，从 1 开始
+     * @param col    列号
      */
     public Token(TokenType type, String lexeme, int line, int col) {
         this(type, lexeme, lexeme, line, col);
     }
 
     /**
-     * 创建一个表示文件结束（EOF）的 Token，列号固定为 1，词素与原始片段均为空字符串。
+     * 构造并返回一个表示文件结束（EOF）的 Token 实例。
+     * <p>
+     * 用于表示扫描结束的特殊符号。
+     * </p>
      *
-     * @param line EOF Token 所在的行号，通常为文件末尾的下一行
+     * @param line 文件结束所在行号
-     * @return 表示 EOF 的 Token 实例
+     * @return EOF 类型的 Token
      */
     public static Token eof(int line) {
         return new Token(TokenType.EOF, "", "", line, 1);
     }
 
-    /**
+    /** @return 此 Token 的类型 */
-     * 获取此 Token 的类型。
-     *
-     * @return Token 类型枚举
-     */
     public TokenType getType() {
         return type;
     }
 
-    /**
+    /** @return 清洗后的词素内容（lexeme） */
-     * 获取清洗后的词素内容。
-     *
-     * @return 词素（lexeme）
-     */
     public String getLexeme() {
         return lexeme;
     }
 
-    /**
+    /** @return 源代码中的原始片段 */
-     * 获取源代码中的原始片段。
-     *
-     * @return 原始片段（raw）
-     */
     public String getRaw() {
         return raw;
     }
 
-    /**
+    /** @return Token 所在的源文件行号（从 1 开始） */
-     * 获取 Token 在源文件中的行号。
-     *
-     * @return 行号，从 1 开始
-     */
     public int getLine() {
         return line;
     }
 
-    /**
+    /** @return Token 所在行的列号（从 1 开始） */
-     * 获取 Token 在源文件行中的列号。
-     *
-     * @return 列号，从 1 开始
-     */
     public int getCol() {
         return col;
     }
 
     /**
-     * 返回 Token 的字符串表示，包含类型、词素、行号和列号，便于调试输出。
+     * 返回该 Token 的字符串表示，包含类型、词素、行列信息。
+     * <p>
+     * 通常用于日志打印或调试目的。
+     * </p>
      *
-     * @return 格式如 Token(type=TYPE, lexeme='value', line=1, col=5)
+     * @return Token 的描述性字符串
      */
     @Override
     public String toString() {
@@ -122,4 +110,4 @@ public class Token {
                 type, lexeme, line, col
         );
     }
-}
+}

src/main/java/org/jcnc/snow/compiler/lexer/token/TokenFactory.java

@@ -3,12 +3,17 @@ package org.jcnc.snow.compiler.lexer.token;
 import java.util.Set;
 
 /**
- * TokenFactory 用于根据原始的词法单元字符串（raw string），
+ * {@code TokenFactory} 是一个静态工厂类，
- * 判断其类型（关键字、类型名、标识符等），并创建对应的 Token 实例。
+ * 用于根据原始的词法单元（字符串文本）
+ * 自动判断其词法类型，并构造对应的 {@link Token} 实例。
+ * <p>
+ * 支持自动识别语言关键字、内置类型名、合法标识符等。
+ * 提供统一的 Token 构建机制，简化词法扫描器的处理逻辑。
+ * </p>
  */
 public class TokenFactory {
 
-    // 关键字集合：包含语言中所有保留关键字
+    /** 语言保留关键字集合 */
     private static final Set<String> KEYWORDS = Set.of(
             "module", "function", "parameter", "return_type",
             "body", "end", "if", "then", "else", "loop",
@@ -16,31 +21,36 @@ public class TokenFactory {
             "initializer", "condition", "update"
     );
 
-    // 类型集合：包含语言中所有内置类型名称
+    /** 内置类型标识集合 */
     private static final Set<String> TYPES = Set.of(
             "int", "string", "float", "bool", "void", "double"
     );
 
     /**
-     * 创建一个 Token 实例。
+     * 创建一个带类型推断的 {@link Token} 实例。
-     * 根据原始字符串判断其类型，并结合位置信息生成 Token。
+     * <p>
+     * 内部依据 {@code raw} 值匹配类型集合、关键字集合，
+     * 若都不匹配则视为合法标识符，否则标记为 {@code UNKNOWN}。
+     * </p>
      *
-     * @param raw  原始字符串（词法单元文本）
+     * @param raw  原始词法单元文本
-     * @param line 所在行号
+     * @param line Token 所在行号
-     * @param col  所在列号
+     * @param col  Token 所在列号
-     * @return 对应类型的 Token 实例
+     * @return 类型明确的 {@link Token} 实例
      */
     public static Token create(String raw, int line, int col) {
-        TokenType type = determineTokenType(raw); // 判断类型
+        TokenType type = determineTokenType(raw);
-        return new Token(type, raw, line, col);   // 创建 Token
+        return new Token(type, raw, line, col);
     }
 
     /**
-     * 判断原始字符串所对应的 Token 类型。
+     * 判定给定字符串所对应的 {@link TokenType}。
-     * 优先级顺序：类型 -> 关键字 -> 标识符 -> 未知。
+     * <p>
+     * 优先级：类型（TYPE） > 关键字（KEYWORD） > 标识符（IDENTIFIER） > 未知（UNKNOWN）
+     * </p>
      *
-     * @param raw 原始词法文本
+     * @param raw 原始词素字符串
-     * @return 对应的 TokenType
+     * @return 推断出的 Token 类型
      */
     private static TokenType determineTokenType(String raw) {
         if (isType(raw)) return TokenType.TYPE;
@@ -50,10 +60,10 @@ public class TokenFactory {
     }
 
     /**
-     * 判断是否为内置类型名称。
+     * 判断是否为内置类型标识。
      *
-     * @param raw 字符串
+     * @param raw 输入字符串
-     * @return 如果是内置类型，则返回 true
+     * @return 若为类型名返回 {@code true}
      */
     private static boolean isType(String raw) {
         return TYPES.contains(raw);
@@ -62,21 +72,23 @@ public class TokenFactory {
     /**
      * 判断是否为语言关键字。
      *
-     * @param raw 字符串
+     * @param raw 输入字符串
-     * @return 如果是关键字，则返回 true
+     * @return 若为关键字返回 {@code true}
      */
     private static boolean isKeyword(String raw) {
         return KEYWORDS.contains(raw);
     }
 
     /**
-     * 判断是否为合法标识符。
+     * 判断是否符合标识符命名规范。
-     * 标识符必须以字母或下划线开头，其后可接字母、数字或下划线。
+     * <p>
+     * 合法标识符需以字母或下划线开头，其后可包含字母、数字或下划线。
+     * </p>
      *
-     * @param raw 字符串
+     * @param raw 输入字符串
-     * @return 如果是合法标识符，则返回 true
+     * @return 若为合法标识符则返回 {@code true}
      */
     private static boolean isIdentifier(String raw) {
         return raw.matches("[a-zA-Z_][a-zA-Z0-9_]*");
     }
-}
+}

src/main/java/org/jcnc/snow/compiler/lexer/token/TokenType.java

@@ -1,9 +1,12 @@
 package org.jcnc.snow.compiler.lexer.token;
 
 /**
- * 表示 Snow 编程语言中的所有词法单元（Token）类型。
+ * {@code TokenType} 枚举定义了 Snow 编程语言词法分析阶段可识别的所有词法单元类型。
  * <p>
- * 这些类型用于标识词法分析阶段识别出的各种语法构成要素。
+ * 每个枚举值代表一种语义类别，
+ * 用于描述源代码中出现的关键字、标识符、字面量、运算符、控制符号等语言构件。
+ * 在语法分析及后续处理阶段，依赖该枚举对 Token 进行分类、判断与分支处理。
+ * </p>
  */
 public enum TokenType {
 
@@ -13,7 +16,7 @@ public enum TokenType {
     /** 语言保留关键字（如 if、return、module 等） */
     KEYWORD,
 
-    /** 类型名（如 int、string、bool 等） */
+    /** 内置类型名称（如 int、string、bool 等） */
     TYPE,
 
     /** 字符串字面量（如 "hello"） */
@@ -22,71 +25,69 @@ public enum TokenType {
     /** 数字字面量（整数或浮点数） */
     NUMBER_LITERAL,
 
-    /** 冒号 ":" */
+    /** 冒号 ':' */
     COLON,
 
-    /** 逗号 "," */
+    /** 逗号 ',' */
     COMMA,
 
-    /** 点号 "." */
+    /** 点号 '.' */
     DOT,
 
-    /** 赋值符号 "=" */
+    /** 赋值符号 '=' */
     EQUALS,
 
-    MODULO, // %
+    /** 取模运算符 '%' */
+    MODULO,
 
-
+    /** 加号 '+' */
-    /** 加号 "+" */
     PLUS,
 
-    /** 乘号 "+" */
+    /** 乘号 '*' */
     MULTIPLY,
 
-    /** 减号 "-" */
+    /** 减号 '-' */
     MINUS,
 
-    /** 左括号 "(" */
+    /** 左括号 '(' */
     LPAREN,
 
-    /** 右括号 ")" */
+    /** 右括号 ')' */
     RPAREN,
 
-    /** 相等比较 "==" */
+    /** 相等比较符号 '==' */
     DOUBLE_EQUALS,
 
-    /** 不等比较 "!=" */
+    /** 不等比较符号 '!=' */
     NOT_EQUALS,
 
-    /** 大于符号 ">" */
+    /** 大于符号 '>' */
     GREATER_THAN,
 
-    /** 大于等于符号 ">=" */
+    /** 大于等于符号 '>=' */
     GREATER_EQUAL,
 
-    /** 小于符号 "<" */
+    /** 小于符号 '<' */
     LESS_THAN,
 
-    /** 小于等于符号 "<=" */
+    /** 小于等于符号 '<=' */
     LESS_EQUAL,
 
-    /** 逻辑与符号 "&&" */
+    /** 逻辑与符号 '&&' */
     AND,
 
-    /** 逻辑或符号 "||" */
+    /** 逻辑或符号 '||' */
     OR,
 
-    /** 换行符，表示逻辑上的新行 */
+    /** 换行符，标识逻辑换行 */
     NEWLINE,
 
-    /** 单行或多行注释 */
+    /** 单行或多行注释内容 */
     COMMENT,
 
     /** 文件结束符（End of File） */
     EOF,
 
     /** 无法识别的非法或未知符号 */
-    UNKNOWN,
+    UNKNOWN
-
+}
-
-}