补充注释。

src/main/java/xyz/zhouxy/plusone/commons/base/Quarter.java

@@ -7,22 +7,41 @@ import com.google.common.base.Preconditions;
 
 import xyz.zhouxy.plusone.commons.util.Numbers;
 
+/**
+ * 季度
+ * 
+ * @author zhouxy
+ */
 public enum Quarter {
+    /** 第一季度 */
     Q1(1, "Q1"),
+    /** 第二季度 */
     Q2(2, "Q2"),
+    /** 第三季度 */
     Q3(3, "Q3"),
+    /** 第四季度 */
     Q4(4, "Q4"),
     ;
 
+    /** 季度值 (1/2/3/4) */
     private final int value;
+    /** 季度名称 */
     private final String displayName;
 
+    /** 季度开始月份 */
     private final int startMonthValue;
+    /** 季度开始日期 */
     private final MonthDay startMonthDay;
 
+    /** 季度结束月份 */
     private final int lastMonthValue;
+    /** 季度结束日期 */
     private final MonthDay lastMonthDay;
 
+    /**
+     * @param value 季度值 (1/2/3/4)
+     * @param str   季度名称
+     */
     Quarter(int value, String str) {
         this.value = value;
         this.displayName = str;
@@ -36,20 +55,47 @@ public enum Quarter {
         this.lastMonthDay = MonthDay.of(lastMonth, (value == 1 || value == 4) ? 31 : 30);
     }
 
+    /**
+     * 根据给定的月份值返回对应的季度
+     * 
+     * @param monthValue 月份值，取值范围为1到12
+     * @return 对应的季度
+     * @throws IllegalArgumentException 如果月份值不在有效范围内（1到12），将抛出异常
+     */
     public static Quarter fromMonth(int monthValue) {
         Preconditions.checkArgument(Numbers.between(monthValue, 1, 13), "Invalid value for MonthOfYear: " + monthValue);
         return of(computeQuarterValueInternal(monthValue));
     }
 
+    /**
+     * 根据给定的月份返回对应的季度
+     * 
+     * @param month 月份
+     * @return 对应的季度
+     */
     public static Quarter fromMonth(Month month) {
         final int monthValue = month.getValue();
         return of(computeQuarterValueInternal(monthValue));
     }
 
+    /**
+     * 根据指定的年份，获取一个新的 YearQuarter 实例
+     * 此方法允许在保持当前季度信息不变的情况下，更改年份
+     *
+     * @param year 指定的年份
+     * @return 返回一个新的 YearQuarter 实例，年份更新为指定的年份
+     */
     public final YearQuarter atYear(int year) {
         return YearQuarter.of(year, this);
     }
 
+    /**
+     * 根据给定的季度值返回对应的季度
+     * 
+     * @param value 季度值 (1/2/3/4)
+     * @return 对应的季度
+     * @throws IllegalArgumentException 如果季度值不在有效范围内（1到4），将抛出异常
+     */
     public static Quarter of(int value) {
         switch (value) {
             case 1:
@@ -65,6 +111,13 @@ public enum Quarter {
         }
     }
 
+    /**
+     * 根据给定的季度名称返回对应的季度
+     * 
+     * @param str 季度名称
+     * @return 对应的季度
+     * @throws IllegalArgumentException 如果季度名称不在有效范围内（Q1/Q2/Q3/Q4），将抛出异常
+     */
     public static Quarter of(String str) {
         switch (str) {
             case "Q1":
@@ -116,11 +169,13 @@ public enum Quarter {
 
     // Getters end
 
+    // Internal
+
     /**
-     * 计算季度
+     * 计算给定月份对应的季度值
      * 
-     * @param monthValue 1~12
-     * @return 季度。1~4
+     * @param monthValue 月份值，取值范围为1到12
+     * @return 对应的季度值
      */
     private static int computeQuarterValueInternal(int monthValue) {
         return (monthValue - 1) / 3 + 1;

src/main/java/xyz/zhouxy/plusone/commons/base/YearQuarter.java

@@ -5,16 +5,29 @@ import java.time.Month;
 import java.time.YearMonth;
 import java.util.Calendar;
 import java.util.Date;
+import java.util.Objects;
+
+import javax.annotation.Nonnull;
 
 import com.google.common.base.Preconditions;
 
+/**
+ * 表示年份与季度
+ * 
+ * @author zhouxy
+ */
 public final class YearQuarter {
+
+    /** 年份 */
     private final int year;
+    /** 季度 */
     private final Quarter quarter;
+    /** 季度开始日期 */
     private final LocalDate startDate;
+    /** 季度结束日期 */
     private final LocalDate lastDate;
 
-    private YearQuarter(int year, Quarter quarter) {
+    private YearQuarter(int year, @Nonnull Quarter quarter) {
         Preconditions.checkNotNull(quarter, "Quarter can not be null.");
         this.year = year;
         this.quarter = quarter;
@@ -22,15 +35,34 @@ public final class YearQuarter {
         this.lastDate = quarter.getLastMonthDay().atYear(year);
     }
 
-    public static YearQuarter of(int year, Quarter quarter) {
+    /**
+     * 根据指定年份与季度，创建 {@link YearQuarter} 实例
+     * 
+     * @param year 年份
+     * @param quarter 季度
+     * @return {@link YearQuarter} 实例
+     */
+    public static YearQuarter of(int year, @Nonnull Quarter quarter) {
         return new YearQuarter(year, quarter);
     }
 
-    public static YearQuarter of(LocalDate date) {
+    /**
+     * 根据指定日期，判断日期所在的年份与季度，创建 {@link YearQuarter} 实例
+     * 
+     * @param date 日期
+     * @return {@link YearQuarter} 实例
+     */
+    public static YearQuarter of(@Nonnull LocalDate date) {
         return new YearQuarter(date.getYear(), Quarter.fromMonth(date.getMonth()));
     }
 
-    public static YearQuarter of(Date date) {
+    /**
+     * 根据指定日期，判断日期所在的年份与季度，创建 {@link YearQuarter} 实例
+     * 
+     * @param date 日期
+     * @return {@link YearQuarter} 实例
+     */
+    public static YearQuarter of(@Nonnull Date date) {
         @SuppressWarnings("deprecation")
         final int year = date.getYear() + 1900;
         @SuppressWarnings("deprecation")
@@ -38,14 +70,28 @@ public final class YearQuarter {
         return of(year, Quarter.fromMonth(month));
     }
 
+    /**
+     * 根据指定日期，判断日期所在的年份与季度，创建 {@link YearQuarter} 实例
+     * 
+     * @param date 日期
+     * @return {@link YearQuarter} 实例
+     */
     public static YearQuarter of(Calendar date) {
         return of(date.get(Calendar.YEAR), Quarter.fromMonth(date.get(Calendar.MONTH) + 1));
     }
 
+    /**
+     * 根据指定年月，判断其所在的年份与季度，创建 {@link YearQuarter} 实例
+     * 
+     * @param yearMonth 年月
+     * @return {@link YearQuarter} 实例
+     */
     public static YearQuarter of(YearMonth yearMonth) {
         return of(yearMonth.getYear(), Quarter.fromMonth(yearMonth.getMonth()));
     }
 
+    // Getters
+
     public int getYear() {
         return year;
     }
@@ -77,4 +123,37 @@ public final class YearQuarter {
     public LocalDate getLastDate() {
         return lastDate;
     }
+
+    // Getters end
+
+    // hashCode & equals
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(year, quarter);
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (this == obj)
+            return true;
+        if (obj == null)
+            return false;
+        if (getClass() != obj.getClass())
+            return false;
+        YearQuarter other = (YearQuarter) obj;
+        return year == other.year && quarter == other.quarter;
+    }
+
+    // toString
+
+    /**
+     * 返回 {@link YearQuarter} 的字符串表示形式，如 "Q3 2024"
+     * 
+     * @return {@link YearQuarter} 的字符串表示形式
+     */
+    @Override
+    public String toString() {
+        return this.quarter.getDisplayName() + " " + this.year;
+    }
 }