添加函数注释

src/main/java/com/mathgenerator/auth/Authenticator.java

@@ -15,6 +15,7 @@ public class Authenticator {
 
     /**
      * 初始化预设的用户数据。这里是暂时定死为这样
+     * @return 一个以用户名为主键，User对象为值的Map。
      */
     private static Map<String, User> initializeUsers() {
         return Stream.of(

src/main/java/com/mathgenerator/generator/JuniorHighSchoolGenerator.java

@@ -11,6 +11,15 @@ import java.util.regex.Pattern;
  * (已重构) 在保留括号和加减乘除的基础上，至少包含一个平方或开根号。
  */
 public class JuniorHighSchoolGenerator extends PrimarySchoolGenerator {
+    /**
+     * 生成一道初中难度的数学题目。
+     * <p>
+     * 此方法首先调用父类（PrimarySchoolGenerator）的同名方法来生成一个
+     * 包含基础运算符和括号的小学题目。然后，它会通过正则表达式找到题目中的
+     * 一个随机数字，并将其替换为它的平方（x²）或开根号（√x）形式。
+     *
+     * @return 一个代表初中数学题目的字符串。
+     */
     @Override
     public String generateSingleQuestion() {
         // 1. 先生成一个完整的小学难度题目（包含括号等）

src/main/java/com/mathgenerator/generator/PrimarySchoolGenerator.java

@@ -12,7 +12,15 @@ import java.util.concurrent.ThreadLocalRandom;
 public class PrimarySchoolGenerator implements QuestionGenerator {
 
     private static final String[] OPERATORS = {"+", "-", "*", "/"};
-
+    /**
+     * 生成一道小学难度的数学题目。
+     * <p>
+     * 该方法会生成一个包含2到5个随机操作数（数值范围1-100）的表达式。
+     * 表达式中会随机包含 "+", "-", "*", "/" 运算符，并有一定概率添加括号
+     * 以增加题目的复杂性。
+     *
+     * @return 一个代表小学数学题目的字符串。
+     */
     @Override
     public String generateSingleQuestion() {
         ThreadLocalRandom random = ThreadLocalRandom.current();

src/main/java/com/mathgenerator/generator/SeniorHighSchoolGenerator.java

@@ -12,7 +12,16 @@ import java.util.regex.Pattern;
  */
 public class SeniorHighSchoolGenerator extends JuniorHighSchoolGenerator { // <-- 关键改动：继承自初中生成器
     private static final String[] TRIG_FUNCTIONS = {"sin", "cos", "tan"};
-
+    /**
+     * 生成一道高中难度的数学题目。
+     * <p>
+     * 此方法首先调用其父类（JuniorHighSchoolGenerator）的同名方法，
+     * 以此获得一个已经包含基础运算、括号以及平方/开根号的初中题目。
+     * 随后，它在该初中题目的基础上，随机选取一个数字，并将其用
+     * sin(), cos(), 或 tan() 函数包裹，从而生成一道高中难度的题目。
+     *
+     * @return 一个代表高中数学题目的字符串。
+     */
     @Override
     public String generateSingleQuestion() {
         // 1. 先生成一个完整的初中难度题目（已包含小学内容和平方/开根号）

src/main/java/com/mathgenerator/model/Level.java

@@ -9,11 +9,19 @@ public enum Level {
     SENIOR_HIGH("高中");
 
     private final String chineseName;
-
+    /**
+     * 枚举的构造函数。
+     *
+     * @param chineseName 学段对应的中文名称。
+     */
     Level(String chineseName) {
         this.chineseName = chineseName;
     }
-
+    /**
+     * 获取学段的中文名称。
+     *
+     * @return 表示学段的中文名称字符串。
+     */
     public String getChineseName() {
         return chineseName;
     }

src/main/java/com/mathgenerator/service/PaperService.java

@@ -17,12 +17,32 @@ public class PaperService {
     private final FileManager fileManager;
     private final PaperStrategy paperStrategy; // 持有策略接口的引用
 
-    // 通过构造函数注入具体的策略实现
+    /**
+     * PaperService的构造函数。
+     * <p>
+     * 通过构造函数注入其依赖的文件管理器和试卷组合策略。
+     * 这种设计遵循了依赖注入（DI）原则，增强了代码的模块化和可测试性。
+     *
+     * @param fileManager   用于处理文件读写的FileManager实例。
+     * @param paperStrategy 用于决定题目组合方式的PaperStrategy实例。
+     */
     public PaperService(FileManager fileManager, PaperStrategy paperStrategy) {
         this.fileManager = fileManager;
         this.paperStrategy = paperStrategy;
     }
-
+    /**
+     * 创建并保存一份完整的试卷。
+     * <p>
+     * 这是该服务的核心方法。它 orchestrates 整个流程：
+     * 1. 加载指定用户的历史题目以进行查重。
+     * 2. 进入循环，委托给注入的 {@link PaperStrategy} 来动态选择题目生成器。
+     * 3. 生成新题目并进行查重，直到满足指定的题目数量。
+     * 4. 调用 {@link FileManager} 将最终的试卷内容保存到文件中。
+     *
+     * @param user         当前已登录的用户对象。
+     * @param count        需要生成的题目数量。
+     * @param currentLevel 用户当前选择的主难度级别。
+     */
     public void createAndSavePaper(User user, int count, Level currentLevel) {
         Set<String> existingQuestions = fileManager.loadExistingQuestions(user.username());
         List<String> newPaper = new ArrayList<>();

src/main/java/com/mathgenerator/service/strategy/MixedDifficultyStrategy.java

@@ -6,6 +6,8 @@ import java.util.concurrent.ThreadLocalRandom;
 
 /**
  * 混合难度策略的具体实现。
+ * <p>
+ * 该策略根据预设的概率，为一份试卷生成包含不同难度级别题目的组合。
  */
 public class MixedDifficultyStrategy implements PaperStrategy {
     // 策略内部持有所有可能的生成器

src/main/java/com/mathgenerator/service/strategy/PaperStrategy.java

@@ -8,5 +8,11 @@ import com.mathgenerator.model.Level;
  * 封装了如何根据主难度来选择具体题目生成器的算法。
  */
 public interface PaperStrategy {
+    /**
+     * 根据用户选择的主难度，选择一个具体的题目生成器。
+     *
+     * @param mainLevel 用户选择的主难度级别。
+     * @return 一个根据策略选择出的QuestionGenerator实例。
+     */
     QuestionGenerator selectGenerator(Level mainLevel);
 }

src/main/java/com/mathgenerator/storage/FileManager.java

@@ -69,7 +69,10 @@ public class FileManager {
             return new HashSet<>();
         }
     }
-
+    /**
+     * @param file 要读取的单个试卷文件的路径对象 (Path)。
+     * @return 一个包含该文件中所有题目字符串的流 (Stream)。如果读取文件时发生 I/O 错误，则会打印错误信息到控制台并返回一个空流。
+     */
     private Stream<String> readQuestionsFromFile(Path file) {
         try {
             //TODO:这里需要修改警告:(72, 26) 在没有 'try-with-resources' 语句的情况下使用 'Stream<String>'

src/main/java/com/mathgenerator/ui/ConsoleUI.java

@@ -16,7 +16,14 @@ public class ConsoleUI {
     private final Authenticator authenticator;
     private final PaperService paperService;
 
-    // 通过构造函数接收依赖的服务，这是一种常见的设计模式（依赖注入）
+    /**
+     * ConsoleUI的构造函数。
+     * 通过构造函数接收依赖的服务，这是一种常见的设计模式（依赖注入），
+     * 使得UI层不负责创建服务，只负责使用。
+     *
+     * @param authenticator 认证服务实例。
+     * @param paperService  试卷服务实例。
+     */
     public ConsoleUI(Authenticator authenticator, PaperService paperService) {
         this.authenticator = authenticator;
         this.paperService = paperService;
@@ -32,7 +39,11 @@ public class ConsoleUI {
             userOptional.ifPresent(this::showUserMenu);
         }
     }
-
+    /**
+     * 私有辅助方法，处理用户登录流程。
+     *
+     * @return 登录成功的用户Optional，如果登录失败或格式错误则返回空Optional。
+     */
     private Optional<User> handleLogin() {
         printHeader("用户登录"); // 统一标题格式
         System.out.print("请输入用户名和密码 (用空格隔开): (输入 exit 退出程序)\n> ");
@@ -55,7 +66,11 @@ public class ConsoleUI {
         }
         return userOptional;
     }
-
+    /**
+     * 私有辅助方法，显示登录后的用户主菜单和处理用户操作。
+     *
+     * @param user 当前已登录的用户对象。
+     */
     private void showUserMenu(User user) {
         Level currentLevel = user.level();
         System.out.println("\n登录成功! 欢迎 " + user.username());
@@ -88,7 +103,10 @@ public class ConsoleUI {
     }
 
     /**
-     * 处理切换难度的子菜单，加入循环以处理无效输入。
+     * 私有辅助方法，处理切换难度的子菜单，加入循环以处理无效输入。
+     *
+     * @param currentLevel 当前的难度级别。
+     * @return 用户选择的新的难度级别，如果选择返回则为原级别。
      */
     private Level handleLevelSwitchMenu(Level currentLevel) {
         while (true) { // <-- 增加循环
@@ -120,7 +138,12 @@ public class ConsoleUI {
             }
         }
     }
-
+    /**
+     * 私有辅助方法，处理生成题目的逻辑。
+     *
+     * @param user         当前登录的用户。
+     * @param currentLevel 当前选择的难度级别。
+     */
     private void handleGeneration(User user, Level currentLevel) {
         printHeader("生成 " + currentLevel.getChineseName() + " 题目");
         System.out.print("请输入生成题目数量 (10-30，输入 0 返回主菜单): ");
@@ -139,13 +162,19 @@ public class ConsoleUI {
             System.out.println("输入无效，请输入一个有效的数字。");
         }
     }
-
+    /**
+     * 私有辅助方法，打印美化后的标题行。
+     *
+     * @param title 要显示的标题文本。
+     */
     private void printHeader(String title) {
         printSeparator();
         System.out.println(title);
         printSeparator();
     }
-
+    /**
+     * 私有辅助方法，打印分割线。
+     */
     private void printSeparator() {
         System.out.println("======================================================");
     }