docs: 完善 javadoc

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

@@ -29,21 +29,50 @@ import javax.annotation.Nullable;
  * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
  */
 public interface IWithCode<T> {
+
+    /**
+     * 获取码值
+     * @return 码值
+     */
     @Nonnull
     T getCode();
 
+    /**
+     * 判断 {@code code} 与给定的值是否相等
+     *
+     * @param code 用于判断的值
+     * @return 判断结果
+     */
     default boolean isCodeEquals(@Nullable T code) {
         return Objects.equals(getCode(), code);
     }
 
+    /**
+     * 判断是否与给定的 {@link IWithCode} 有着相等的 {@code code}
+     *
+     * @param other 用于比较的对象
+     * @return 判断结果
+     */
     default boolean isSameCodeAs(@Nullable IWithCode<?> other) {
         return other != null && Objects.equals(getCode(), other.getCode());
     }
 
+    /**
+     * 判断是否与给定的 {@link IWithIntCode} 有着相等的 {@code code}
+     *
+     * @param other 用于比较的对象
+     * @return 判断结果
+     */
     default boolean isSameCodeAs(@Nullable IWithIntCode other) {
         return other != null && Objects.equals(getCode(), other.getCode());
     }
 
+    /**
+     * 判断是否与给定的 {@link IWithLongCode} 有着相等的 {@code code}
+     *
+     * @param other 用于比较的对象
+     * @return 判断结果
+     */
     default boolean isSameCodeAs(@Nullable IWithLongCode other) {
         return other != null && Objects.equals(getCode(), other.getCode());
     }

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

@@ -28,20 +28,49 @@ import javax.annotation.Nullable;
  * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
  */
 public interface IWithIntCode {
+
+    /**
+     * 获取码值
+     * @return 码值
+     */
     int getCode();
 
+    /**
+     * 判断 {@code code} 与给定的值是否相等
+     *
+     * @param code 用于判断的值
+     * @return 判断结果
+     */
     default boolean isCodeEquals(int code) {
         return getCode() == code;
     }
 
+    /**
+     * 判断是否与给定的 {@link IWithCode} 有着相等的 {@code code}
+     *
+     * @param other 用于比较的对象
+     * @return 判断结果
+     */
     default boolean isSameCodeAs(@Nullable IWithCode<?> other) {
         return other != null && Objects.equals(getCode(), other.getCode());
     }
 
+    /**
+     * 判断是否与给定的 {@link IWithIntCode} 有着相等的 {@code code}
+     *
+     * @param other 用于比较的对象
+     * @return 判断结果
+     */
     default boolean isSameCodeAs(@Nullable IWithIntCode other) {
         return other != null && getCode() == other.getCode();
     }
 
+    /**
+     * 判断是否与给定的 {@link IWithLongCode} 有着相等的 {@code code}
+     *
+     * @param other 用于比较的对象
+     * @return 判断结果
+     */
     default boolean isSameCodeAs(@Nullable IWithLongCode other) {
         return other != null && getCode() == other.getCode();
     }

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

@@ -28,20 +28,49 @@ import javax.annotation.Nullable;
  * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
  */
 public interface IWithLongCode {
+
+    /**
+     * 获取码值
+     * @return 码值
+     */
     long getCode();
 
+    /**
+     * 判断 {@code code} 与给定的值是否相等
+     *
+     * @param code 用于判断的值
+     * @return 判断结果
+     */
     default boolean isCodeEquals(long code) {
         return getCode() == code;
     }
 
+    /**
+     * 判断是否与给定的 {@link IWithCode} 有着相等的 {@code code}
+     *
+     * @param other 用于比较的对象
+     * @return 判断结果
+     */
     default boolean isSameCodeAs(@Nullable IWithCode<?> other) {
         return other != null && Objects.equals(getCode(), other.getCode());
     }
 
+    /**
+     * 判断是否与给定的 {@link IWithIntCode} 有着相等的 {@code code}
+     *
+     * @param other 用于比较的对象
+     * @return 判断结果
+     */
     default boolean isSameCodeAs(@Nullable IWithIntCode other) {
         return other != null && getCode() == other.getCode();
     }
 
+    /**
+     * 判断是否与给定的 {@link IWithLongCode} 有着相等的 {@code code}
+     *
+     * @param other 用于比较的对象
+     * @return 判断结果
+     */
     default boolean isSameCodeAs(@Nullable IWithLongCode other) {
         return other != null && getCode() == other.getCode();
     }

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

@@ -79,43 +79,100 @@ public final class Ref<T> {
         this.value = value;
     }
 
+    /**
+     * 创建对象引用
+     *
+     * @param <T>   引用的类型
+     * @param value 引用的对象
+     * @return {@code Ref} 对象
+     */
     public static <T> Ref<T> of(@Nullable T value) {
         return new Ref<>(value);
     }
 
+    /**
+     * 创建空引用
+     *
+     * @param <T>   引用的类型
+     * @return 空引用
+     */
     public static <T> Ref<T> empty() {
         return new Ref<>(null);
     }
 
+    /**
+     * 获取引用的对象
+     *
+     * @return 引用的对象
+     */
     @Nullable
     public T getValue() {
         return value;
     }
 
+    /**
+     * 设置引用的对象
+     *
+     * @param value 要引用的对象
+     */
     public void setValue(@Nullable T value) {
         this.value = value;
     }
 
+    /**
+     * 使用 {@link UnaryOperator} 修改 {@code Ref} 内部引用的对象
+     *
+     * @param operator 修改逻辑
+     */
     public void transformValue(UnaryOperator<T> operator) {
         this.value = operator.apply(this.value);
     }
 
+    /**
+     * 使用 {@link Function} 修改所引用的对象，返回新的 {@code Ref}
+     *
+     * @param <R>      结果的引用类型
+     * @param function 修改逻辑
+     * @return 修改后的对象的引用
+     */
     public <R> Ref<R> transform(Function<? super T, R> function) {
         return Ref.of(function.apply(this.value));
     }
 
+    /**
+     * 使用 {@link Predicate} 检查引用的对象
+     *
+     * @param predicate 判断逻辑
+     * @return 判断结果
+     */
     public boolean checkValue(Predicate<? super T> predicate) {
         return predicate.test(this.value);
     }
 
+    /**
+     * 将引用的对象作为入参，执行 {@link Consumer} 的逻辑
+     *
+     * @param consumer 要执行的逻辑
+     */
     public void execute(Consumer<? super T> consumer) {
         consumer.accept(value);
     }
 
+    /**
+     * 判断所引用的对象是否为 {@code null}
+     *
+     * @return 是否为 {@code null}
+     */
     public boolean isNull() {
         return this.value == null;
     }
 
+
+    /**
+     * 判断所引用的对象是否不为 {@code null}
+     *
+     * @return 是否不为 {@code null}
+     */
     public boolean isNotNull() {
         return this.value != null;
     }

src/main/java/xyz/zhouxy/plusone/commons/collection/CollectionTools.java

@@ -42,26 +42,62 @@ public class CollectionTools {
     // #region - isEmpty
     // ================================
 
+    /**
+     * 判断集合是否为空
+     *
+     * @param collection 集合
+     * @return 是否为空
+     */
     public static boolean isEmpty(@Nullable Collection<?> collection) {
         return collection == null || collection.isEmpty();
     }
 
+    /**
+     * 判断集合是否为空
+     *
+     * @param map 集合
+     * @return 是否为空
+     */
     public static boolean isEmpty(@Nullable Map<?, ?> map) {
         return map == null || map.isEmpty();
     }
 
+    /**
+     * 判断集合是否为空
+     *
+     * @param table 集合
+     * @return 是否为空
+     */
     public static boolean isEmpty(@Nullable Table<?, ?, ?> table) {
         return table == null || table.isEmpty();
     }
 
+    /**
+     * 判断集合是否为空
+     *
+     * @param map 集合
+     * @return 是否为空
+     */
     public static boolean isEmpty(@Nullable Multimap<?, ?> map) {
         return map == null || map.isEmpty();
     }
 
+    /**
+     * 判断集合是否为空
+     *
+     * @param set 集合
+     * @return 是否为空
+     */
     public static boolean isEmpty(@Nullable Multiset<?> set) {
         return set == null || set.isEmpty();
     }
 
+    /**
+     * 判断集合是否为空
+     *
+     * @param set 集合
+     * @return 是否为空
+     */
     public static boolean isEmpty(@Nullable RangeSet<?> set) {
         return set == null || set.isEmpty();
     }
@@ -74,26 +110,62 @@ public class CollectionTools {
     // #region - isNotEmpty
     // ================================
 
+    /**
+     * 判断集合是否不为空
+     *
+     * @param collection 集合
+     * @return 是否不为空
+     */
     public static boolean isNotEmpty(@Nullable Collection<?> collection) {
         return collection != null && !collection.isEmpty();
     }
 
+    /**
+     * 判断集合是否不为空
+     *
+     * @param map 集合
+     * @return 是否不为空
+     */
     public static boolean isNotEmpty(@Nullable Map<?, ?> map) {
         return map != null && !map.isEmpty();
     }
 
+    /**
+     * 判断集合是否不为空
+     *
+     * @param table 集合
+     * @return 是否不为空
+     */
     public static boolean isNotEmpty(@Nullable Table<?, ?, ?> table) {
         return table != null && !table.isEmpty();
     }
 
+    /**
+     * 判断集合是否不为空
+     *
+     * @param map 集合
+     * @return 是否不为空
+     */
     public static boolean isNotEmpty(@Nullable Multimap<?, ?> map) {
         return map != null && !map.isEmpty();
     }
 
+    /**
+     * 判断集合是否不为空
+     *
+     * @param set 集合
+     * @return 是否不为空
+     */
     public static boolean isNotEmpty(@Nullable Multiset<?> set) {
         return set != null && !set.isEmpty();
     }
 
+    /**
+     * 判断集合是否不为空
+     *
+     * @param set 集合
+     * @return 是否不为空
+     */
     public static boolean isNotEmpty(@Nullable RangeSet<?> set) {
         return set != null && !set.isEmpty();
     }
@@ -106,16 +178,41 @@ public class CollectionTools {
     // #region - nullToEmpty
     // ================================
 
+    /**
+     * 将 {@code null} 转为空 {@code List}
+     *
+     * @param <T> List 元素的类型
+     * @param list list
+     * @return 如果 {@code list} 为 {@code null}，返回空列表；
+     *         如果 {@code list} 不为 {@code null}，返回 {@code list} 本身
+     */
     @Nonnull
     public static <T> List<T> nullToEmptyList(@Nullable List<T> list) {
         return list == null ? Collections.emptyList() : list;
     }
 
+    /**
+     * 将 {@code null} 转为空 {@code Set}
+     *
+     * @param <T> Set 元素的类型
+     * @param set set
+     * @return 如果 {@code set} 为 {@code null}，返回空集合；
+     *         如果 {@code set} 不为 {@code null}，返回 {@code set} 本身
+     */
     @Nonnull
     public static <T> Set<T> nullToEmptySet(@Nullable Set<T> set) {
         return set == null ? Collections.emptySet() : set;
     }
 
+    /**
+     * 将 {@code null} 转为空 {@code Map}
+     *
+     * @param <K> Map 的键的类型
+     * @param <V> Map 的值的类型
+     * @param map map
+     * @return 如果 {@code map} 为 {@code null}，返回空集合；
+     *         如果 {@code map} 不为 {@code null}，返回 {@code map} 本身
+     */
     @Nonnull
     public static <K, V> Map<K, V> nullToEmptyMap(@Nullable Map<K, V> map) {
         return map == null ? Collections.emptyMap() : map;

src/main/java/xyz/zhouxy/plusone/commons/exception/DataNotExistsException.java

@@ -26,18 +26,40 @@ public final class DataNotExistsException extends Exception {
 
     private static final long serialVersionUID = 6536955800679703111L;
 
+    /**
+     * 使用默认 message 构造新的 {@code DataNotExistsException}。
+     * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。
+     */
     public DataNotExistsException() {
         super();
     }
 
+    /**
+     * 使用指定的 {@code message} 构造新的 {@code DataNotExistsException}。
+     * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。
+     *
+     * @param message 异常信息
+     */
     public DataNotExistsException(String message) {
         super(message);
     }
 
+    /**
+     * 使用指定的 {@code cause} 构造新的 {@code DataNotExistsException}。
+     * {@code message} 为 (cause==null ? null : cause.toString())。
+     *
+     * @param cause 包装的异常
+     */
     public DataNotExistsException(Throwable cause) {
         super(cause);
     }
 
+    /**
+     * 使用指定的 {@code message} 和 {@code cause} 构造新的 {@code DataNotExistsException}。
+     *
+     * @param message 异常信息
+     * @param cause   包装的异常
+     */
     public DataNotExistsException(String message, Throwable cause) {
         super(message, cause);
     }

src/main/java/xyz/zhouxy/plusone/commons/exception/MultiTypesException.java

@@ -124,26 +124,66 @@ import xyz.zhouxy.plusone.commons.base.IWithCode;
  */
 public interface MultiTypesException<E extends Exception, T extends MultiTypesException.ExceptionType<E>> {
 
+    /**
+     * 异常类型
+     *
+     * @return 异常类型。通常是实现了 {@link ExceptionType} 的枚举。
+     */
     @Nonnull
     T getType();
 
+    /**
+     * 获取异常类型编码
+     *
+     * @return 异常类型编码
+     */
     default @Nonnull String getTypeCode() {
         return getType().getCode();
     }
 
+    /**
+     * 异常类型
+     */
     public static interface ExceptionType<E extends Exception> extends IWithCode<String> {
 
+        /**
+         * 默认异常信息
+         */
         String getDefaultMessage();
 
+        /**
+         * 创建异常
+         *
+         * @return 异常对象
+         */
         @Nonnull
         E create();
 
+        /**
+         * 使用指定 {@code message} 创建异常
+         *
+         * @param message 异常信息
+         * @return 异常对象
+         */
         @Nonnull
         E create(String message);
 
+        /**
+         * 使用指定 {@code cause} 创建异常
+         *
+         * @param cause 包装的异常
+         * @return 异常对象
+         */
         @Nonnull
         E create(Throwable cause);
 
+        /**
+         * 使用指定 {@code message} 和 {@code cause} 创建异常
+         *
+         * @param message 异常信息
+         * @param cause   包装的异常
+         * @return 异常对象
+         */
         @Nonnull
         E create(String message, Throwable cause);
 

src/main/java/xyz/zhouxy/plusone/commons/exception/ParsingFailureException.java

@@ -59,22 +59,56 @@ public final class ParsingFailureException
         this.type = type;
     }
 
+    /**
+     * 创建默认类型的 {@code ParsingFailureException}。
+     * {@code type} 为 {@link Type#DEFAULT}，
+     * {@code message} 为 {@link Type#DEFAULT} 的默认信息。
+     * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。
+     */
     public ParsingFailureException() {
         this(Type.DEFAULT, Type.DEFAULT.getDefaultMessage());
     }
 
+    /**
+     * 使用指定 {@code message} 创建默认类型的 {@code ParsingFailureException}。
+     * {@code type} 为 {@link Type#DEFAULT}，
+     * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。
+     *
+     * @param message 异常信息
+     */
     public ParsingFailureException(String message) {
         this(Type.DEFAULT, message);
     }
 
+    /**
+     * 使用指定的 {@code cause} 创建默认类型的 {@code ParsingFailureException}。
+     * {@code type} 为 {@link Type#DEFAULT}，
+     * {@code message} 为 (cause==null ? null : cause.toString())。
+     *
+     * @param cause 包装的异常
+     */
     public ParsingFailureException(Throwable cause) {
         this(Type.DEFAULT, cause);
     }
 
+    /**
+     * 使用指定的 {@code message} 和 {@code cause} 创建默认类型的 {@code ParsingFailureException}。
+     * {@code type} 为 {@link Type#DEFAULT}。
+     *
+     * @param message 异常信息
+     * @param cause   包装的异常
+     */
     public ParsingFailureException(String message, Throwable cause) {
         this(Type.DEFAULT, message, cause);
     }
 
+    /**
+     * 将 {@link DateTimeParseException} 包装为 {@link ParsingFailureException}。
+     * {@code type} 为 {@link Type#DATE_TIME_PARSING_FAILURE}。
+     *
+     * @param cause 包装的 {@code DateTimeParseException}
+     * @return ParsingFailureException
+     */
     public static ParsingFailureException of(DateTimeParseException cause) {
         if (cause == null) {
             return Type.DATE_TIME_PARSING_FAILURE.create();
@@ -82,10 +116,25 @@ public final class ParsingFailureException
         return Type.DATE_TIME_PARSING_FAILURE.create(cause.getMessage(), cause);
     }
 
+    /**
+     * 将 {@link DateTimeParseException} 包装为 {@link ParsingFailureException}。
+     * {@code type} 为 {@link Type#DATE_TIME_PARSING_FAILURE}。
+     *
+     * @param message 异常信息
+     * @param cause   包装的 {@code DateTimeParseException}
+     * @return ParsingFailureException
+     */
     public static ParsingFailureException of(String message, DateTimeParseException cause) {
         return Type.DATE_TIME_PARSING_FAILURE.create(message, cause);
     }
 
+    /**
+     * 将 {@link NumberFormatException} 包装为 {@link ParsingFailureException}。
+     * {@code type} 为 {@link Type#NUMBER_PARSING_FAILURE}。
+     *
+     * @param cause 包装的 {@code NumberFormatException}
+     * @return ParsingFailureException
+     */
     public static ParsingFailureException of(NumberFormatException cause) {
         if (cause == null) {
             return Type.NUMBER_PARSING_FAILURE.create();
@@ -93,6 +142,14 @@ public final class ParsingFailureException
         return Type.NUMBER_PARSING_FAILURE.create(cause.getMessage(), cause);
     }
 
+    /**
+     * 将 {@link NumberFormatException} 包装为 {@link ParsingFailureException}。
+     * {@code type} 为 {@link Type#NUMBER_PARSING_FAILURE}。
+     *
+     * @param message 异常信息
+     * @param cause   {@code NumberFormatException}
+     * @return ParsingFailureException
+     */
     public static ParsingFailureException of(String message, NumberFormatException cause) {
         return Type.NUMBER_PARSING_FAILURE.create(message, cause);
     }
@@ -103,10 +160,15 @@ public final class ParsingFailureException
         return type;
     }
 
+    /** 默认类型 */
     public static final Type DEFAULT = Type.DEFAULT;
+    /** 数字转换失败 */
     public static final Type NUMBER_PARSING_FAILURE = Type.NUMBER_PARSING_FAILURE;
+    /** 时间解析失败 */
     public static final Type DATE_TIME_PARSING_FAILURE = Type.DATE_TIME_PARSING_FAILURE;
+    /** JSON 解析失败 */
     public static final Type JSON_PARSING_FAILURE = Type.JSON_PARSING_FAILURE;
+    /** XML 解析失败 */
     public static final Type XML_PARSING_FAILURE = Type.XML_PARSING_FAILURE;
 
     public enum Type implements ExceptionType<ParsingFailureException> {

src/main/java/xyz/zhouxy/plusone/commons/exception/business/BizException.java

@@ -33,18 +33,40 @@ public class BizException extends RuntimeException {
 
     private static final String DEFAULT_MSG = "业务异常";
 
+    /**
+     * 使用默认 message 构造新的业务异常。
+     * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。
+     */
     public BizException() {
         super(DEFAULT_MSG);
     }
 
+    /**
+     * 使用指定的 {@code message} 构造新的业务异常。
+     * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。
+     *
+     * @param message 异常信息
+     */
     public BizException(String message) {
         super(message);
     }
 
+    /**
+     * 使用指定的 {@code cause} 构造新的业务异常。
+     * {@code message} 为 (cause==null ? null : cause.toString())。
+     *
+     * @param cause 包装的异常
+     */
     public BizException(Throwable cause) {
         super(cause);
     }
 
+    /**
+     * 使用指定的 {@code message} 和 {@code cause} 构造新的业务异常。
+     *
+     * @param message 异常信息
+     * @param cause   包装的异常
+     */
     public BizException(String message, Throwable cause) {
         super(message, cause);
     }

src/main/java/xyz/zhouxy/plusone/commons/exception/business/InvalidInputException.java

@@ -60,18 +60,45 @@ public final class InvalidInputException
         this.type = type;
     }
 
+    /**
+     * 创建默认类型的 {@code InvalidInputException}。
+     * {@code type} 为 {@link Type#DEFAULT}，
+     * {@code message} 为 {@link Type#DEFAULT} 的默认信息。
+     * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。
+     */
     public InvalidInputException() {
         this(Type.DEFAULT);
     }
 
+    /**
+     * 使用指定 {@code message} 创建默认类型的 {@code InvalidInputException}。
+     * {@code type} 为 {@link Type#DEFAULT}，
+     * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。
+     *
+     * @param message 异常信息
+     */
     public InvalidInputException(String message) {
         this(Type.DEFAULT, message);
     }
 
+    /**
+     * 使用指定的 {@code cause} 创建默认类型的 {@code InvalidInputException}。
+     * {@code type} 为 {@link Type#DEFAULT}，
+     * {@code message} 为 (cause==null ? null : cause.toString())。
+     *
+     * @param cause 包装的异常
+     */
     public InvalidInputException(Throwable cause) {
         this(Type.DEFAULT, cause);
     }
 
+    /**
+     * 使用指定的 {@code message} 和 {@code cause} 创建默认类型的 {@code InvalidInputException}。
+     * {@code type} 为 {@link Type#DEFAULT}。
+     *
+     * @param message 异常信息
+     * @param cause   包装的异常
+     */
     public InvalidInputException(String message, Throwable cause) {
         this(Type.DEFAULT, message, cause);
     }

src/main/java/xyz/zhouxy/plusone/commons/exception/business/RequestParamsException.java

@@ -30,18 +30,40 @@ public class RequestParamsException extends BizException {
 
     private static final String DEFAULT_MSG = "用户请求参数错误";
 
+    /**
+     * 使用默认 message 构造新的 {@code RequestParamsException}。
+     * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。
+     */
     public RequestParamsException() {
         super(DEFAULT_MSG);
     }
 
+    /**
+     * 使用指定的 {@code message} 构造新的 {@code RequestParamsException}。
+     * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。
+     *
+     * @param message 异常信息
+     */
     public RequestParamsException(String message) {
         super(message);
     }
 
+    /**
+     * 使用指定的 {@code cause} 构造新的 {@code RequestParamsException}。
+     * {@code message} 为 (cause==null ? null : cause.toString())。
+     *
+     * @param cause 包装的异常
+     */
     public RequestParamsException(Throwable cause) {
         super(cause);
     }
 
+    /**
+     * 使用指定的 {@code message} 和 {@code cause} 构造新的 {@code RequestParamsException}。
+     *
+     * @param message 异常信息
+     * @param cause   包装的异常
+     */
     public RequestParamsException(String message, Throwable cause) {
         super(message, cause);
     }

src/main/java/xyz/zhouxy/plusone/commons/exception/system/DataOperationResultException.java

@@ -35,18 +35,40 @@ public final class DataOperationResultException extends SysException {
 
     private static final String DEFAULT_MSG = "数据操作的结果不符合预期";
 
+    /**
+     * 使用默认 message 构造新的 {@code DataOperationResultException}。
+     * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。
+     */
     public DataOperationResultException() {
         super(DEFAULT_MSG);
     }
 
+    /**
+     * 使用指定的 {@code message} 构造新的 {@code DataOperationResultException}。
+     * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。
+     *
+     * @param message 异常信息
+     */
     public DataOperationResultException(String message) {
         super(message);
     }
 
+    /**
+     * 使用指定的 {@code cause} 构造新的 {@code DataOperationResultException}。
+     * {@code message} 为 (cause==null ? null : cause.toString())。
+     *
+     * @param cause 包装的异常
+     */
     public DataOperationResultException(Throwable cause) {
         super(cause);
     }
 
+    /**
+     * 使用指定的 {@code message} 和 {@code cause} 构造新的 {@code DataOperationResultException}。
+     *
+     * @param message 异常信息
+     * @param cause   包装的异常
+     */
     public DataOperationResultException(String message, Throwable cause) {
         super(message, cause);
     }

src/main/java/xyz/zhouxy/plusone/commons/exception/system/NoAvailableMacFoundException.java

@@ -29,18 +29,40 @@ package xyz.zhouxy.plusone.commons.exception.system;
 public class NoAvailableMacFoundException extends SysException {
     private static final long serialVersionUID = 152827098461071551L;
 
+    /**
+     * 使用默认 message 构造新的 {@code NoAvailableMacFoundException}。
+     * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。
+     */
     public NoAvailableMacFoundException() {
         super();
     }
 
+    /**
+     * 使用指定的 {@code message} 构造新的 {@code NoAvailableMacFoundException}。
+     * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。
+     *
+     * @param message 异常信息
+     */
     public NoAvailableMacFoundException(String message) {
         super(message);
     }
 
+    /**
+     * 使用指定的 {@code cause} 构造新的 {@code NoAvailableMacFoundException}。
+     * {@code message} 为 (cause==null ? null : cause.toString())。
+     *
+     * @param cause 包装的异常
+     */
     public NoAvailableMacFoundException(Throwable cause) {
         super(cause);
     }
 
+    /**
+     * 使用指定的 {@code message} 和 {@code cause} 构造新的 {@code NoAvailableMacFoundException}。
+     *
+     * @param message 异常信息
+     * @param cause   包装的异常
+     */
     public NoAvailableMacFoundException(String message, Throwable cause) {
         super(message, cause);
     }

src/main/java/xyz/zhouxy/plusone/commons/exception/system/SysException.java

@@ -30,18 +30,40 @@ public class SysException extends RuntimeException {
 
     private static final String DEFAULT_MSG = "系统异常";
 
+    /**
+     * 使用默认 message 构造新的系统异常。
+     * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。
+     */
     public SysException() {
         super(DEFAULT_MSG);
     }
 
+    /**
+     * 使用指定的 {@code message} 构造新的系统异常。
+     * {@code cause} 未初始化，后面可能会通过调用 {@link #initCause} 进行初始化。
+     *
+     * @param message 异常信息
+     */
     public SysException(String message) {
         super(message);
     }
 
+    /**
+     * 使用指定的 {@code cause} 构造新的系统异常。
+     * {@code message} 为 (cause==null ? null : cause.toString())。
+     *
+     * @param cause 包装的异常
+     */
     public SysException(Throwable cause) {
         super(cause);
     }
 
+    /**
+     * 使用指定的 {@code message} 和 {@code cause} 构造新的系统异常。
+     *
+     * @param message 异常信息
+     * @param cause   包装的异常
+     */
     public SysException(String message, Throwable cause) {
         super(message, cause);
     }

src/main/java/xyz/zhouxy/plusone/commons/function/BoolUnaryOperator.java

@@ -18,11 +18,35 @@ package xyz.zhouxy.plusone.commons.function;
 
 import com.google.common.annotations.Beta;
 
+/**
+ * BoolUnaryOperator
+ *
+ * <p>
+ * 一个特殊的 {@link java.util.function.UnaryOperator}。
+ * 表示对 {@code boolean} 值的一元操作。
+ * </p>
+ *
+ * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
+ * @since 1.0.0
+ * @see java.util.function.UnaryOperator
+ */
 @Beta
 @FunctionalInterface
 public interface BoolUnaryOperator {
+
+    /**
+     * 将此函数应用于给定的 {@code boolean} 参数，返回一个 {@code boolean} 结果。
+     *
+     * @param operand 操作数
+     * @return 结果
+     */
     boolean applyAsBool(boolean operand);
 
+    /**
+     * 返回一个 {@code BoolUnaryOperator}，该操作符将给定的操作数取反。
+     *
+     * @return {@code BoolUnaryOperator}
+     */
     static BoolUnaryOperator not() {
         return b -> !b;
     }

src/main/java/xyz/zhouxy/plusone/commons/function/CharUnaryOperator.java

@@ -18,8 +18,27 @@ package xyz.zhouxy.plusone.commons.function;
 
 import com.google.common.annotations.Beta;
 
+/**
+ * CharUnaryOperator
+ *
+ * <p>
+ * 一个特殊的 {@link java.util.function.UnaryOperator}。
+ * 表示对 {@code char} 的一元操作。
+ * </p>
+ *
+ * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
+ * @since 1.0.0
+ * @see java.util.function.UnaryOperator
+ */
 @Beta
 @FunctionalInterface
 public interface CharUnaryOperator {
+
+    /**
+     * 将此函数应用于给定的 {@code char} 参数，返回一个 {@code char} 结果。
+     *
+     * @param operand 操作数
+     * @return 结果
+     */
     char applyAsChar(char operand);
 }

src/main/java/xyz/zhouxy/plusone/commons/function/Executable.java

@@ -16,9 +16,26 @@
 
 package xyz.zhouxy.plusone.commons.function;
 
+/**
+ * Executable
+ *
+ * <p>
+ * 表示一个无入参无返回值的操作，可抛出异常。
+ * </p>
+ *
+ * @param <E> 可抛出的异常类型
+ *
+ * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
+ * @since 1.0.0
+ */
 @FunctionalInterface
 public interface Executable<E extends Throwable> {
 
+    /**
+     * 执行
+     *
+     * @throws E 可抛出的异常
+     */
     void execute() throws E;
 
 }

src/main/java/xyz/zhouxy/plusone/commons/function/OptionalSupplier.java

@@ -24,6 +24,7 @@ import java.util.function.Supplier;
  *
  * <p>
  * 返回 {@code Optional&lt;T&gt;} 对象。
+ * </p>
  *
  * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
  * @since 1.0.0

src/main/java/xyz/zhouxy/plusone/commons/function/ThrowingConsumer.java

@@ -16,13 +16,24 @@
 
 package xyz.zhouxy.plusone.commons.function;
 
+/**
+ * ThrowingConsumer
+ *
+ * <p>
+ * 允许抛出异常的消费操作。是一个特殊的 {@link java.util.function.Consumer}。
+ * </p>
+ *
+ * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
+ * @since 1.0.0
+ * @see java.util.function.Consumer
+ */
 @FunctionalInterface
 public interface ThrowingConsumer<T, E extends Throwable> {
 
     /**
-     * Consume the supplied argument, potentially throwing an exception.
+     * 消费给定的参数，允许抛出异常
      *
-     * @param t the argument to consume
+     * @param t 要消费的参数
      */
     void accept(T t) throws E;
 

src/main/java/xyz/zhouxy/plusone/commons/function/ThrowingFunction.java

@@ -15,14 +15,29 @@
  */
 package xyz.zhouxy.plusone.commons.function;
 
+/**
+ * ThrowingFunction
+ *
+ * <p>
+ * 接收一个参数，并返回一个结果，可以抛出异常。
+ * </p>
+ *
+ * @param <T> 入参类型
+ * @param <R> 返回结果类型
+ * @param <E> 异常类型
+ *
+ * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
+ * @since 1.0
+ * @see java.util.function.Function
+ */
 @FunctionalInterface
 public interface ThrowingFunction<T, R, E extends Throwable> {
 
     /**
-     * Applies this function to the given argument.
+     * 接收一个参数，并返回一个结果，可以抛出异常。
      *
-     * @param t the function argument
+     * @param t 入参
-     * @return the function result
+     * @return 函数结果
      */
     R apply(T t) throws E;
 

src/main/java/xyz/zhouxy/plusone/commons/function/ThrowingPredicate.java

@@ -16,15 +16,25 @@
 
 package xyz.zhouxy.plusone.commons.function;
 
+/**
+ * ThrowingPredicate
+ *
+ * <p>
+ * 接收一个参数，返回一个布尔值，可抛出异常。
+ * </p>
+ *
+ * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
+ * @since 1.0.0
+ * @see java.util.function.Predicate
+ */
 @FunctionalInterface
 public interface ThrowingPredicate<T, E extends Throwable> {
 
     /**
-     * Evaluates this predicate on the given argument.
+     * 对给定的参数进行评估
      *
-     * @param t the input argument
+     * @param t 入参
-     * @return {@code true} if the input argument matches the predicate,
+     * @return 入参符合条件时返回 {@code true}，否则返回 {@code false}
-     * otherwise {@code false}
      */
     boolean test(T t) throws E;
 }

src/main/java/xyz/zhouxy/plusone/commons/function/ThrowingSupplier.java

@@ -16,13 +16,27 @@
 
 package xyz.zhouxy.plusone.commons.function;
 
+/**
+ * ThrowingSupplier
+ *
+ * <p>
+ * 允许抛出异常的 Supplier 接口。
+ * </p>
+ *
+ * @param <T> 结果类型
+ * @param <E> 异常类型
+ *
+ * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
+ * @since 1.0.0
+ * @see java.util.function.Supplier
+ */
 @FunctionalInterface
 public interface ThrowingSupplier<T, E extends Throwable> {
 
     /**
-     * Get a result, potentially throwing an exception.
+     * 获取一个结果，允许抛出异常。
      *
-     * @return a result
+     * @return 结果
      */
     T get() throws E;
 

src/main/java/xyz/zhouxy/plusone/commons/model/Chinese2ndGenIDCardNumber.java

@@ -79,6 +79,12 @@ public class Chinese2ndGenIDCardNumber
         this.birthDate = birthDate;
     }
 
+    /**
+     * 根据身份证号码创建 {@code Chinese2ndGenIDCardNumber} 对象
+     *
+     * @param idCardNumber 身份证号码值
+     * @return {@code Chinese2ndGenIDCardNumber} 对象
+     */
     public static Chinese2ndGenIDCardNumber of(final String idCardNumber) {
         try {
             AssertTools.checkArgument(StringTools.isNotBlank(idCardNumber), "二代居民身份证校验失败：号码为空");
@@ -120,36 +126,71 @@ public class Chinese2ndGenIDCardNumber
         return value;
     }
 
+    /**
+     * 所属省份代码
+     *
+     * @return 所属省份代码
+     */
     @ReaderMethod
     public String getProvinceCode() {
         return provinceCode;
     }
 
+    /**
+     * 所属省份名称
+     *
+     * @return 所属省份名称
+     */
     @ReaderMethod
     public String getProvinceName() {
         return PROVINCE_CODES.get(this.provinceCode);
     }
 
+    /**
+     * 所属省份完整行政区划代码
+     *
+     * @return 所属省份完整行政区划代码
+     */
     @ReaderMethod
     public String getFullProvinceCode() {
         return Strings.padEnd(this.provinceCode, 12, '0');
     }
 
+    /**
+     * 所属市级代码
+     *
+     * @return 所属市级代码
+     */
     @ReaderMethod
     public String getCityCode() {
         return cityCode;
     }
 
+    /**
+     * 所属市级完整行政区划代码
+     *
+     * @return 所属市级完整行政区划代码
+     */
     @ReaderMethod
     public String getFullCityCode() {
         return Strings.padEnd(this.cityCode, 12, '0');
     }
 
+    /**
+     * 所属县级代码
+     *
+     * @return 所属县级代码
+     */
     @ReaderMethod
     public String getCountyCode() {
         return countyCode;
     }
 
+    /**
+     * 所属县级完整行政区划代码
+     *
+     * @return 所属县级完整行政区划代码
+     */
     @ReaderMethod
     public String getFullCountyCode() {
         return Strings.padEnd(this.countyCode, 12, '0');

src/main/java/xyz/zhouxy/plusone/commons/model/Gender.java

@@ -43,20 +43,41 @@ public enum Gender implements IWithIntCode {
         this.displayNameZh = displayNameZh;
     }
 
+    /**
+     * 根据码值获取对应枚举
+     *
+     * @param value 码值
+     * @return 枚举值
+     */
     public static Gender of(int value) {
         AssertTools.checkCondition(0 <= value && value < VALUES.length,
                 () -> new EnumConstantNotPresentException(Gender.class, String.valueOf(value)));
         return VALUES[value];
     }
 
+    /**
+     * 获取枚举码值
+     *
+     * @return 码值
+     */
     public int getValue() {
         return value;
     }
 
+    /**
+     * 枚举名称
+     *
+     * @return 枚举名称
+     */
     public String getDisplayName() {
         return displayName;
     }
 
+    /**
+     * 枚举中文名称
+     *
+     * @return 枚举中文名称
+     */
     public String getDisplayNameZh() {
         return displayNameZh;
     }

src/main/java/xyz/zhouxy/plusone/commons/model/IDCardNumber.java

@@ -30,20 +30,31 @@ public interface IDCardNumber {
     static final int DEFAULT_DISPLAY_FRONT = 1;
     static final int DEFAULT_DISPLAY_END = 2;
 
+    /**
+     * 身份证号
+     *
+     * @return 身份证号
+     */
     String value();
 
     /**
      * 根据身份证号判断性别
+     *
+     * @return {@link Gender} 对象
      */
     Gender getGender();
 
     /**
      * 获取出生日期
+     *
+     * @return 出生日期
      */
     LocalDate getBirthDate();
 
     /**
      * 计算年龄
+     *
+     * @return 年龄
      */
     default int getAge() {
         LocalDate now = LocalDate.now();
@@ -54,14 +65,34 @@ public interface IDCardNumber {
     // #region - toString
     // ================================
 
+    /**
+     * 脱敏字符串（前面留 1 位，后面留 2 位）
+     *
+     * @return 脱敏字符串
+     */
     default String toDesensitizedString() {
         return StringTools.desensitize(value(), DEFAULT_REPLACED_CHAR, DEFAULT_DISPLAY_FRONT, DEFAULT_DISPLAY_END);
     }
 
+    /**
+     * 脱敏字符串
+     *
+     * @param front 前面保留的字符数
+     * @param end   后面保留的字符数
+     * @return 脱敏字符串
+     */
     default String toDesensitizedString(int front, int end) {
         return StringTools.desensitize(value(), DEFAULT_REPLACED_CHAR, front, end);
     }
 
+    /**
+     * 脱敏字符串
+     *
+     * @param replacedChar 替换字符
+     * @param front        前面保留的字符数
+     * @param end          后面保留的字符数
+     * @return 脱敏字符串
+     */
     default String toDesensitizedString(char replacedChar, int front, int end) {
         return StringTools.desensitize(value(), replacedChar, front, end);
     }

src/main/java/xyz/zhouxy/plusone/commons/model/ValidatableStringRecord.java

@@ -36,7 +36,7 @@ import xyz.zhouxy.plusone.commons.util.AssertTools;
  * @deprecated 弃用。使用工厂方法创建对象，并在其中进行校验即可。
  */
 @Deprecated
-public abstract class ValidatableStringRecord<T extends ValidatableStringRecord<T>>
+public abstract class ValidatableStringRecord<T extends ValidatableStringRecord<T>> // NOSONAR 暂不删除
         implements Comparable<T> {
 
     @Nonnull
@@ -44,15 +44,35 @@ public abstract class ValidatableStringRecord<T extends ValidatableStringRecord<
 
     private final Matcher matcher;
 
+    /**
+     * 构造字符串值对象
+     *
+     * @param value   字符串值
+     * @param pattern 正则
+     */
     protected ValidatableStringRecord(String value, Pattern pattern) {
         this(value, pattern, "Invalid value");
     }
 
+    /**
+     * 构造字符串值对象
+     *
+     * @param value                字符串值
+     * @param pattern              正则
+     * @param errorMessageSupplier 正则不匹配时的错误信息
+     */
     protected ValidatableStringRecord(String value, Pattern pattern,
             Supplier<String> errorMessageSupplier) {
         this(value, pattern, errorMessageSupplier.get());
     }
 
+    /**
+     * 构造字符串值对象
+     *
+     * @param value        字符串值
+     * @param pattern      正则
+     * @param errorMessage 正则不匹配时的错误信息
+     */
     protected ValidatableStringRecord(String value, Pattern pattern, String errorMessage) {
         AssertTools.checkArgument(Objects.nonNull(value), "The value cannot be null.");
         AssertTools.checkArgument(Objects.nonNull(pattern), "The pattern cannot be null.");
@@ -99,6 +119,11 @@ public abstract class ValidatableStringRecord<T extends ValidatableStringRecord<
         return this.value();
     }
 
+    /**
+     * 获取正则匹配结果
+     *
+     * @return {@code Matcher} 对象
+     */
     protected final Matcher getMatcher() {
         return matcher;
     }

src/main/java/xyz/zhouxy/plusone/commons/model/dto/PageResult.java

@@ -43,20 +43,44 @@ public class PageResult<T> {
         this.total = total;
     }
 
+    /**
+     * 创建一个分页查询的结果
+     *
+     * @param <T>     内容类型
+     * @param content 一页数据
+     * @param total   总数据量
+     * @return 分页查询的结果
+     */
     @StaticFactoryMethod(PageResult.class)
     public static <T> PageResult<T> of(@Nullable final List<T> content, final long total) {
         return new PageResult<>(content, total);
     }
 
+    /**
+     * 创建一个空的分页查询的结果
+     *
+     * @param <T> 内容类型
+     * @return 空结果
+     */
     @StaticFactoryMethod(PageResult.class)
     public static <T> PageResult<T> empty() {
         return new PageResult<>(Collections.emptyList(), 0L);
     }
 
+    /**
+     * 总数据量
+     *
+     * @return 总数据量
+     */
     public long getTotal() {
         return total;
     }
 
+    /**
+     * 一页数据
+     *
+     * @return 一页数据
+     */
     public List<T> getContent() {
         return content;
     }

src/main/java/xyz/zhouxy/plusone/commons/model/dto/PagingAndSortingQueryParams.java

@@ -54,6 +54,11 @@ public class PagingAndSortingQueryParams {
 
     private final Map<String, String> sortableProperties;
 
+    /**
+     * 构造分页排序查询参数
+     *
+     * @param sortableProperties 可排序的属性。不可为空。
+     */
     public PagingAndSortingQueryParams(Map<String, String> sortableProperties) {
         AssertTools.checkArgument(CollectionTools.isNotEmpty(sortableProperties),
                 "Sortable properties can not be empty.");
@@ -74,16 +79,31 @@ public class PagingAndSortingQueryParams {
         this.orderBy = orderBy;
     }
 
+    /**
+     * 设置每页大小
+     *
+     * @param size 每页大小
+     */
     public final void setSize(@Nullable Integer size) {
         this.size = size;
     }
 
+    /**
+     * 设置页码
+     *
+     * @param pageNum 页码
+     */
     public final void setPageNum(@Nullable Long pageNum) {
         this.pageNum = pageNum;
     }
 
     // Setters end
 
+    /**
+     * 构建分页参数
+     *
+     * @return {@code PagingParams} 对象
+     */
     public final PagingParams buildPagingParams() {
         final int sizeValue = this.size != null ? this.size : defaultSizeInternal();
         final long pageNumValue = this.pageNum != null ? this.pageNum : 1L;
@@ -95,6 +115,13 @@ public class PagingAndSortingQueryParams {
         return new PagingParams(sizeValue, pageNumValue, propertiesToSort);
     }
 
+    /**
+     * 默认每页大小
+     *
+     * <p>NOTE: 可覆写此方法</p>
+     *
+     * @return 默认每页大小
+     */
     @Virtual
     protected int defaultSizeInternal() {
         return DEFAULT_PAGE_SIZE;
@@ -124,6 +151,9 @@ public class PagingAndSortingQueryParams {
         return new SortableProperty(propertyName, columnName, orderType);
     }
 
+    /**
+     * 可排序属性
+     */
     public static final class SortableProperty {
         private final String propertyName;
         private final String columnName;
@@ -140,18 +170,38 @@ public class PagingAndSortingQueryParams {
             this.sqlSnippet = this.propertyName + " " + this.orderType;
         }
 
+        /**
+         * 属性名
+         *
+         * @return 属性名
+         */
         public String getPropertyName() {
             return propertyName;
         }
 
+        /**
+         * 对应数据库中列名称
+         *
+         * @return 列名称
+         */
         public String getColumnName() {
             return columnName;
         }
 
+        /**
+         * 排序方式
+         *
+         * @return 排序方式
+         */
         public String getOrderType() {
             return orderType;
         }
 
+        /**
+         * SQL 片段
+         *
+         * @return SQL 片段
+         */
         public String getSqlSnippet() {
             return sqlSnippet;
         }

src/main/java/xyz/zhouxy/plusone/commons/model/dto/PagingParams.java

@@ -23,9 +23,13 @@ import xyz.zhouxy.plusone.commons.model.dto.PagingAndSortingQueryParams.Sortable
 
 public class PagingParams {
 
+    /** 每页大小 */
     private final int size;
+    /** 当前页码 */
     private final long pageNum;
+    /** 偏移量 */
     private final long offset;
+    /** 排序 */
     private final List<SortableProperty> orderBy;
 
     PagingParams(int size, long pageNum, List<SortableProperty> orderBy) {
@@ -37,18 +41,38 @@ public class PagingParams {
 
     // Getters
 
+    /**
+     * 排序规则
+     *
+     * @return 排序规则
+     */
     public final List<SortableProperty> getOrderBy() {
         return Collections.unmodifiableList(this.orderBy);
     }
 
+    /**
+     * 每页大小
+     *
+     * @return 每页大小
+     */
     public final int getSize() {
         return this.size;
     }
 
+    /**
+     * 当前页码
+     *
+     * @return 当前页码
+     */
     public final long getPageNum() {
         return this.pageNum;
     }
 
+    /**
+     * 偏移量
+     *
+     * @return 偏移量
+     */
     public final long getOffset() {
         return this.offset;
     }

src/main/java/xyz/zhouxy/plusone/commons/model/dto/UnifiedResponse.java

@@ -35,10 +35,23 @@ public class UnifiedResponse<T> {
     // #region - Constructors
     // ================================
 
+    /**
+     * 构造 {@code UnifiedResponse}
+     *
+     * @param code    状态码
+     * @param message 响应信息
+     */
     UnifiedResponse(String code, @Nullable String message) {
         this(code, message, null);
     }
 
+    /**
+     * 构造 {@code UnifiedResponse}
+     *
+     * @param code    状态码
+     * @param message 响应信息
+     * @param data    响应数据
+     */
     UnifiedResponse(String code, @Nullable String message, @Nullable T data) {
         this.code = Objects.requireNonNull(code);
         this.message = message == null ? "" : message;
@@ -53,14 +66,29 @@ public class UnifiedResponse<T> {
     // #region - Getters
     // ================================
 
+    /**
+     * 状态码
+     *
+     * @return 状态码
+     */
     public String getCode() {
         return code;
     }
 
+    /**
+     * 响应信息
+     *
+     * @return 响应信息
+     */
     public String getMessage() {
         return message;
     }
 
+    /**
+     * 响应数据
+     *
+     * @return 响应数据
+     */
     @Nullable
     public T getData() {
         return data;

src/main/java/xyz/zhouxy/plusone/commons/model/dto/UnifiedResponses.java

@@ -34,14 +34,36 @@ public class UnifiedResponses {
     // #region - success
     // ================================
 
+    /**
+     * 默认成功响应结果
+     *
+     * @return {@code UnifiedResponse} 对象。
+     *         {@code code} = "2000000", {@code message} = "SUCCESS", {@code data} = null
+     */
     public static UnifiedResponse<Void> success() {
         return new UnifiedResponse<>(SUCCESS_CODE, DEFAULT_SUCCESS_MSG);
     }
 
+    /**
+     * 使用指定 {@code message} 创建成功响应结果
+     *
+     * @param message 成功信息
+     * @return {@code UnifiedResponse} 对象。
+     *         {@code code} = "2000000", {@code data} = null
+     */
     public static UnifiedResponse<Void> success(@Nullable String message) {
         return new UnifiedResponse<>(SUCCESS_CODE, message);
     }
 
+    /**
+     * 使用指定 {@code message} 和 {@code data} 创建成功响应结果
+     *
+     * @param <T>     data 类型
+     * @param message 成功信息
+     * @param data    携带数据
+     * @return {@code UnifiedResponse} 对象。
+     *         {@code code} = "2000000"
+     */
     public static <T> UnifiedResponse<T> success(@Nullable String message, @Nullable T data) {
         return new UnifiedResponse<>(SUCCESS_CODE, message, data);
     }
@@ -54,14 +76,39 @@ public class UnifiedResponses {
     // #region - error
     // ================================
 
+    /**
+     * 创建错误响应结果
+     *
+     * @param code    错误码
+     * @param message 错误信息
+     * @return {@code UnifiedResponse} 对象（{@code data} 为 {@code null}）
+     */
     public static UnifiedResponse<Void> error(String code, @Nullable String message) {
         return new UnifiedResponse<>(code, message);
     }
 
+    /**
+     * 创建错误响应结果
+     *
+     * @param <T>     data 类型
+     * @param code    错误码
+     * @param message 错误信息
+     * @param data    携带数据
+     * @return {@code UnifiedResponse} 对象
+     */
     public static <T> UnifiedResponse<T> error(String code, @Nullable String message, @Nullable T data) {
         return new UnifiedResponse<>(code, message, data);
     }
 
+    /**
+     * 创建错误响应结果
+     *
+     * @param code 错误码
+     * @param e    异常
+     * @return {@code UnifiedResponse} 对象。
+     *         {@code message} 为异常的 {@code message}，
+     *         {@code data} 为 {@code null}。
+     */
     public static UnifiedResponse<Void> error(String code, Throwable e) {
         return new UnifiedResponse<>(code, e.getMessage());
     }
@@ -74,10 +121,26 @@ public class UnifiedResponses {
     // #region - of
     // ================================
 
+    /**
+     * 创建响应结果
+     *
+     * @param code    状态码
+     * @param message 响应信息
+     * @return {@code UnifiedResponse} 对象（{@code data} 为 {@code null}）
+     */
     public static UnifiedResponse<Void> of(String code, @Nullable String message) {
         return new UnifiedResponse<>(code, message);
     }
 
+    /**
+     * 创建响应结果
+     *
+     * @param <T>     data 类型
+     * @param code    状态码
+     * @param message 响应信息
+     * @param data    携带数据
+     * @return {@code UnifiedResponse} 对象
+     */
     public static <T> UnifiedResponse<T> of(String code, @Nullable String message, @Nullable T data) {
         return new UnifiedResponse<>(code, message, data);
     }

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

@@ -46,6 +46,7 @@ public enum Quarter implements IWithIntCode {
     /** 季度值 (1/2/3/4) */
     private final int value;
 
+    /** 月份范围 */
     private final Range<Integer> monthRange;
 
     /** 常量值 */
@@ -63,7 +64,9 @@ public enum Quarter implements IWithIntCode {
         this.monthRange = Range.closed(firstMonth, lastMonth);
     }
 
-    // StaticFactoryMethods
+    // ================================
+    // #region - StaticFactoryMethods
+    // ================================
 
     /**
      * 根据给定的月份值返回对应的季度
@@ -114,23 +117,48 @@ public enum Quarter implements IWithIntCode {
         return ENUMS[checkValidIntValue(value) - 1];
     }
 
-    // StaticFactoryMethods end
+    // ================================
+    // #endregion - StaticFactoryMethods
+    // ================================
 
-    // computes
+    // ================================
+    // #region - computes
+    // ================================
 
+    /**
+     * 加上指定数量的季度
+     *
+     * @param quarters 所添加的季度数量
+     * @return 计算结果
+     */
     public Quarter plus(long quarters) {
         final int amount = (int) ((quarters % 4) + 4);
         return ENUMS[(ordinal() + amount) % 4];
     }
 
+    /**
+     * 减去指定数量的季度
+     *
+     * @param quarters 所减去的季度数量
+     * @return 计算结果
+     */
     public Quarter minus(long quarters) {
         return plus(-(quarters % 4));
     }
 
-    // computes end
+    // ================================
+    // #endregion - computes
+    // ================================
 
-    // Getters
+    // ================================
+    // #region - Getters
+    // ================================
 
+    /**
+     * 获取季度值
+     *
+     * @return 季度值
+     */
     public int getValue() {
         return value;
     }
@@ -140,45 +168,92 @@ public enum Quarter implements IWithIntCode {
         return getValue();
     }
 
+    /**
+     * 该季度的第一个月
+     *
+     * @return {@code Month} 对象
+     */
     public Month firstMonth() {
         return Month.of(firstMonthValue());
     }
 
+    /**
+     * 该季度的第一个月
+     *
+     * @return 月份值从 1 开始，1 表示 1月，以此类推。
+     */
     public int firstMonthValue() {
         return this.monthRange.lowerEndpoint();
     }
 
+    /**
+     * 该季度的最后一个月
+     *
+     * @return {@code Month} 对象
+     */
     public Month lastMonth() {
         return Month.of(lastMonthValue());
     }
 
+    /**
+     * 该季度的最后一个月
+     *
+     * @return 月份值从 1 开始，1 表示 1月，以此类推。
+     */
     public int lastMonthValue() {
         return this.monthRange.upperEndpoint();
     }
 
+    /**
+     * 该季度的第一天
+     *
+     * @return {@code MonthDay} 对象
+     */
     public MonthDay firstMonthDay() {
         return MonthDay.of(firstMonth(), 1);
     }
 
+    /**
+     * 该季度的最后一天
+     *
+     * @return {@code MonthDay} 对象
+     */
     public MonthDay lastMonthDay() {
         // 季度的最后一个月不可能是 2 月
         final Month month = lastMonth();
         return MonthDay.of(month, month.maxLength());
     }
 
+    /**
+     * 计算该季度的第一天为当年的第几天
+     *
+     * @param leapYear 是否为闰年
+     * @return day of year
+     */
     public int firstDayOfYear(boolean leapYear) {
         return firstMonth().firstDayOfYear(leapYear);
     }
 
-    // Getters end
+    // ================================
+    // #endregion - Getters
+    // ================================
 
+    /**
+     * 检查给定的季度值是否有效
+     *
+     * @param value 季度值
+     * @return 如果给定的季度值有效则返回该值
+     * @throws DateTimeException 如果给定的季度值不在有效范围内（1到4），将抛出异常
+     */
     public static int checkValidIntValue(int value) {
         AssertTools.checkCondition(value >= 1 && value <= 4,
                 () -> new DateTimeException("Invalid value for Quarter: " + value));
         return value;
     }
 
-    // Internal
+    // ================================
+    // #region - Internal
+    // ================================
 
     /**
      * 计算给定月份对应的季度值
@@ -189,4 +264,8 @@ public enum Quarter implements IWithIntCode {
     private static int computeQuarterValueInternal(int monthValue) {
         return (monthValue - 1) / 3 + 1;
     }
+
+    // ================================
+    // #endregion - Internal
+    // ================================
 }

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

@@ -139,6 +139,11 @@ public final class YearQuarter implements Comparable<YearQuarter>, Serializable
         return of(yearMonth.getYear(), Quarter.fromMonth(yearMonth.getMonth()));
     }
 
+    /**
+     * 根据现在的日期，判断所在的年份与季度，创建 {@link YearQuarter} 实例
+     *
+     * @return {@link YearQuarter} 实例
+     */
     @StaticFactoryMethod(YearQuarter.class)
     public static YearQuarter now() {
         return of(LocalDate.now());
@@ -148,46 +153,101 @@ public final class YearQuarter implements Comparable<YearQuarter>, Serializable
 
     // #region - Getters
 
+    /**
+     * 年份
+     *
+     * @return 年份
+     */
     public int getYear() {
         return this.year;
     }
 
+    /**
+     * 季度
+     *
+     * @return 季度
+     */
     public Quarter getQuarter() {
         return this.quarter;
     }
 
+    /**
+     * 季度值。从 1 开始。
+     *
+     * @return 季度值
+     */
     public int getQuarterValue() {
         return this.quarter.getValue();
     }
 
+    /**
+     * 该季度第一个月
+     *
+     * @return {@link YearMonth} 对象
+     */
     public YearMonth firstYearMonth() {
         return YearMonth.of(this.year, this.quarter.firstMonth());
     }
 
+    /**
+     * 该季度第一个月
+     *
+     * @return {@link Month} 对象
+     */
     public Month firstMonth() {
         return this.quarter.firstMonth();
     }
 
+    /**
+     * 该季度的第一个月
+     *
+     * @return 结果。月份值从 1 开始，1 表示 1月，以此类推。
+     */
     public int firstMonthValue() {
         return this.quarter.firstMonthValue();
     }
 
+    /**
+     * 该季度的最后一个月
+     *
+     * @return {@link YearMonth} 对象
+     */
     public YearMonth lastYearMonth() {
         return YearMonth.of(this.year, this.quarter.lastMonth());
     }
 
+    /**
+     * 该季度的最后一个月
+     *
+     * @return {@link Month} 对象
+     */
     public Month lastMonth() {
         return this.quarter.lastMonth();
     }
 
+    /**
+     * 该季度的最后一个月
+     *
+     * @return 结果。月份值从 1 开始，1 表示 1月，以此类推。
+     */
     public int lastMonthValue() {
         return this.quarter.lastMonthValue();
     }
 
+    /**
+     * 该季度的第一天
+     *
+     * @return {@link LocalDate} 对象
+     */
     public LocalDate firstDate() {
         return firstDate;
     }
 
+    /**
+     * 该季度的最后一天
+     *
+     * @return {@link LocalDate} 对象
+     */
     public LocalDate lastDate() {
         return lastDate;
     }
@@ -223,7 +283,7 @@ public final class YearQuarter implements Comparable<YearQuarter>, Serializable
         if (yearsToAdd == 0L) {
             return this;
         }
-        int newYear = YEAR.checkValidIntValue(this.year + yearsToAdd);  // safe overflow
+        int newYear = YEAR.checkValidIntValue(this.year + yearsToAdd); // safe overflow
         return new YearQuarter(newYear, this.quarter);
     }
 

src/main/java/xyz/zhouxy/plusone/commons/util/ArrayTools.java

@@ -470,10 +470,24 @@ public class ArrayTools {
 
     // repeat - char
 
+    /**
+     * 重复数组中的元素
+     *
+     * @param arr   重复内容
+     * @param times 重复次数
+     * @return 重复后的数组
+     */
     public static char[] repeat(char[] arr, int times) {
         return repeat(arr, times, Integer.MAX_VALUE);
     }
 
+    /**
+     * 重复数组中的元素
+     * @param arr       重复内容
+     * @param times     重复次数
+     * @param maxLength 最大长度
+     * @return 重复后的数组
+     */
     public static char[] repeat(char[] arr, int times, int maxLength) {
         AssertTools.checkArgument(Objects.nonNull(arr));
         AssertTools.checkArgument(times >= 0,
@@ -491,10 +505,24 @@ public class ArrayTools {
 
     // repeat - byte
 
+    /**
+     * 重复数组中的元素
+     *
+     * @param arr   重复内容
+     * @param times 重复次数
+     * @return 重复后的数组
+     */
     public static byte[] repeat(byte[] arr, int times) {
         return repeat(arr, times, Integer.MAX_VALUE);
     }
 
+    /**
+     * 重复数组中的元素
+     * @param arr       重复内容
+     * @param times     重复次数
+     * @param maxLength 最大长度
+     * @return 重复后的数组
+     */
     public static byte[] repeat(byte[] arr, int times, int maxLength) {
         AssertTools.checkArgument(Objects.nonNull(arr));
         AssertTools.checkArgument(times >= 0,
@@ -512,10 +540,24 @@ public class ArrayTools {
 
     // repeat - short
 
+    /**
+     * 重复数组中的元素
+     *
+     * @param arr   重复内容
+     * @param times 重复次数
+     * @return 重复后的数组
+     */
     public static short[] repeat(short[] arr, int times) {
         return repeat(arr, times, Integer.MAX_VALUE);
     }
 
+    /**
+     * 重复数组中的元素
+     * @param arr       重复内容
+     * @param times     重复次数
+     * @param maxLength 最大长度
+     * @return 重复后的数组
+     */
     public static short[] repeat(short[] arr, int times, int maxLength) {
         AssertTools.checkArgument(Objects.nonNull(arr));
         AssertTools.checkArgument(times >= 0,
@@ -533,10 +575,24 @@ public class ArrayTools {
 
     // repeat - int
 
+    /**
+     * 重复数组中的元素
+     *
+     * @param arr   重复内容
+     * @param times 重复次数
+     * @return 重复后的数组
+     */
     public static int[] repeat(int[] arr, int times) {
         return repeat(arr, times, Integer.MAX_VALUE);
     }
 
+    /**
+     * 重复数组中的元素
+     * @param arr       重复内容
+     * @param times     重复次数
+     * @param maxLength 最大长度
+     * @return 重复后的数组
+     */
     public static int[] repeat(int[] arr, int times, int maxLength) {
         AssertTools.checkArgument(Objects.nonNull(arr));
         AssertTools.checkArgument(times >= 0,
@@ -554,10 +610,24 @@ public class ArrayTools {
 
     // repeat - long
 
+    /**
+     * 重复数组中的元素
+     *
+     * @param arr   重复内容
+     * @param times 重复次数
+     * @return 重复后的数组
+     */
     public static long[] repeat(long[] arr, int times) {
         return repeat(arr, times, Integer.MAX_VALUE);
     }
 
+    /**
+     * 重复数组中的元素
+     * @param arr       重复内容
+     * @param times     重复次数
+     * @param maxLength 最大长度
+     * @return 重复后的数组
+     */
     public static long[] repeat(long[] arr, int times, int maxLength) {
         AssertTools.checkArgument(Objects.nonNull(arr));
         AssertTools.checkArgument(times >= 0,
@@ -575,10 +645,24 @@ public class ArrayTools {
 
     // repeat - float
 
+    /**
+     * 重复数组中的元素
+     *
+     * @param arr   重复内容
+     * @param times 重复次数
+     * @return 重复后的数组
+     */
     public static float[] repeat(float[] arr, int times) {
         return repeat(arr, times, Integer.MAX_VALUE);
     }
 
+    /**
+     * 重复数组中的元素
+     * @param arr       重复内容
+     * @param times     重复次数
+     * @param maxLength 最大长度
+     * @return 重复后的数组
+     */
     public static float[] repeat(float[] arr, int times, int maxLength) {
         AssertTools.checkArgument(Objects.nonNull(arr));
         AssertTools.checkArgument(times >= 0,
@@ -596,10 +680,24 @@ public class ArrayTools {
 
     // repeat - double
 
+    /**
+     * 重复数组中的元素
+     *
+     * @param arr   重复内容
+     * @param times 重复次数
+     * @return 重复后的数组
+     */
     public static double[] repeat(double[] arr, int times) {
         return repeat(arr, times, Integer.MAX_VALUE);
     }
 
+    /**
+     * 重复数组中的元素
+     * @param arr       重复内容
+     * @param times     重复次数
+     * @param maxLength 最大长度
+     * @return 重复后的数组
+     */
     public static double[] repeat(double[] arr, int times, int maxLength) {
         AssertTools.checkArgument(Objects.nonNull(arr));
         AssertTools.checkArgument(times >= 0,
@@ -621,14 +719,34 @@ public class ArrayTools {
 
     // fill - char
 
+    /**
+     * 填充数组
+     *
+     * @param a      要填充的数组
+     * @param values 填充内容
+     */
     public static void fill(char[] a, @Nullable char[] values) {
         fill(a, 0, a.length, values);
     }
 
+    /**
+     * 填充数组
+     *
+     * @param a      要填充的数组
+     * @param values 填充内容
+     */
     public static void fill(char[] a, @Nullable String values) {
         fill(a, 0, a.length, values != null ? values.toCharArray() : EMPTY_CHAR_ARRAY);
     }
 
+    /**
+     * 填充数组
+     *
+     * @param a         要填充的数组
+     * @param fromIndex 开始位置
+     * @param toIndex   结束位置
+     * @param values    填充内容
+     */
     public static void fill(char[] a, int fromIndex, int toIndex, @Nullable char[] values) {
         AssertTools.checkArgument(Objects.nonNull(a));
         if (values == null || values.length == 0) {
@@ -654,10 +772,24 @@ public class ArrayTools {
 
     // fill - byte
 
+    /**
+     * 填充数组
+     *
+     * @param a      要填充的数组
+     * @param values 填充内容
+     */
     public static void fill(byte[] a, @Nullable byte[] values) {
         fill(a, 0, a.length, values);
     }
 
+    /**
+     * 填充数组
+     *
+     * @param a         要填充的数组
+     * @param fromIndex 开始位置
+     * @param toIndex   结束位置
+     * @param values    填充内容
+     */
     public static void fill(byte[] a, int fromIndex, int toIndex, @Nullable byte[] values) {
         AssertTools.checkArgument(Objects.nonNull(a));
         if (values == null || values.length == 0) {
@@ -683,10 +815,24 @@ public class ArrayTools {
 
     // fill - short
 
+    /**
+     * 填充数组
+     *
+     * @param a      要填充的数组
+     * @param values 填充内容
+     */
     public static void fill(short[] a, @Nullable short[] values) {
         fill(a, 0, a.length, values);
     }
 
+    /**
+     * 填充数组
+     *
+     * @param a         要填充的数组
+     * @param fromIndex 开始位置
+     * @param toIndex   结束位置
+     * @param values    填充内容
+     */
     public static void fill(short[] a, int fromIndex, int toIndex, @Nullable short[] values) {
         AssertTools.checkArgument(Objects.nonNull(a));
         if (values == null || values.length == 0) {
@@ -712,10 +858,24 @@ public class ArrayTools {
 
     // fill - int
 
+    /**
+     * 填充数组
+     *
+     * @param a      要填充的数组
+     * @param values 填充内容
+     */
     public static void fill(int[] a, @Nullable int[] values) {
         fill(a, 0, a.length, values);
     }
 
+    /**
+     * 填充数组
+     *
+     * @param a         要填充的数组
+     * @param fromIndex 开始位置
+     * @param toIndex   结束位置
+     * @param values    填充内容
+     */
     public static void fill(int[] a, int fromIndex, int toIndex, @Nullable int[] values) {
         AssertTools.checkArgument(Objects.nonNull(a));
         if (values == null || values.length == 0) {
@@ -741,10 +901,24 @@ public class ArrayTools {
 
     // fill - long
 
+    /**
+     * 填充数组
+     *
+     * @param a      要填充的数组
+     * @param values 填充内容
+     */
     public static void fill(long[] a, @Nullable long[] values) {
         fill(a, 0, a.length, values);
     }
 
+    /**
+     * 填充数组
+     *
+     * @param a         要填充的数组
+     * @param fromIndex 开始位置
+     * @param toIndex   结束位置
+     * @param values    填充内容
+     */
     public static void fill(long[] a, int fromIndex, int toIndex, @Nullable long[] values) {
         AssertTools.checkArgument(Objects.nonNull(a));
         if (values == null || values.length == 0) {
@@ -770,10 +944,24 @@ public class ArrayTools {
 
     // fill - float
 
+    /**
+     * 填充数组
+     *
+     * @param a      要填充的数组
+     * @param values 填充内容
+     */
     public static void fill(float[] a, @Nullable float[] values) {
         fill(a, 0, a.length, values);
     }
 
+    /**
+     * 填充数组
+     *
+     * @param a         要填充的数组
+     * @param fromIndex 开始位置
+     * @param toIndex   结束位置
+     * @param values    填充内容
+     */
     public static void fill(float[] a, int fromIndex, int toIndex, @Nullable float[] values) {
         AssertTools.checkArgument(Objects.nonNull(a));
         if (values == null || values.length == 0) {
@@ -799,10 +987,24 @@ public class ArrayTools {
 
     // fill - double
 
+    /**
+     * 填充数组
+     *
+     * @param a      要填充的数组
+     * @param values 填充内容
+     */
     public static void fill(double[] a, @Nullable double[] values) {
         fill(a, 0, a.length, values);
     }
 
+    /**
+     * 填充数组
+     *
+     * @param a         要填充的数组
+     * @param fromIndex 开始位置
+     * @param toIndex   结束位置
+     * @param values    填充内容
+     */
     public static void fill(double[] a, int fromIndex, int toIndex, @Nullable double[] values) {
         AssertTools.checkArgument(Objects.nonNull(a));
         if (values == null || values.length == 0) {
@@ -828,14 +1030,36 @@ public class ArrayTools {
 
     // fill - T
 
+    /**
+     * 填充数组
+     *
+     * @param a      要填充的数组
+     * @param values 填充内容
+     */
     public static <T> void fill(T[] a, @Nullable T[] values) {
         fillInternal(a, 0, a.length, values);
     }
 
+    /**
+     * 填充数组
+     *
+     * @param a         要填充的数组
+     * @param fromIndex 开始位置
+     * @param toIndex   结束位置
+     * @param values    填充内容
+     */
     public static <T> void fill(T[] a, int fromIndex, int toIndex, @Nullable T[] values) {
         fillInternal(a, fromIndex, toIndex, values);
     }
 
+    /**
+     * 填充数组
+     *
+     * @param a         要填充的数组
+     * @param fromIndex 开始位置
+     * @param toIndex   结束位置
+     * @param values    填充内容
+     */
     private static <T> void fillInternal(T[] a, int fromIndex, int toIndex, @Nullable T[] values) {
         AssertTools.checkArgument(Objects.nonNull(a));
         if (values == null || values.length == 0) {

src/main/java/xyz/zhouxy/plusone/commons/util/AssertTools.java

@@ -49,22 +49,46 @@ public class AssertTools {
     // #region - Argument
     // ================================
 
-    /** Throw {@link IllegalArgumentException} if the {@code condition} is false. */
+    /**
+     * 检查实参
+     *
+     * @param condition 判断参数是否符合条件的结果
+     * @throws IllegalArgumentException 当条件不满足时抛出
+     */
     public static void checkArgument(boolean condition) {
         checkCondition(condition, IllegalArgumentException::new);
     }
 
-    /** Throw {@link IllegalArgumentException} if the {@code condition} is false. */
+    /**
+     * 检查实参
+     *
+     * @param condition 判断参数是否符合条件的结果
+     * @param errMsg    异常信息
+     * @throws IllegalArgumentException 当条件不满足时抛出
+     */
     public static void checkArgument(boolean condition, @Nullable String errMsg) {
         checkCondition(condition, () -> new IllegalArgumentException(errMsg));
     }
 
-    /** Throw {@link IllegalArgumentException} if the {@code condition} is false. */
+    /**
+     * 检查实参
+     *
+     * @param condition       判断参数是否符合条件的结果
+     * @param messageSupplier 异常信息
+     * @throws IllegalArgumentException 当条件不满足时抛出
+     */
     public static void checkArgument(boolean condition, Supplier<String> messageSupplier) {
         checkCondition(condition, () -> new IllegalArgumentException(messageSupplier.get()));
     }
 
-    /** Throw {@link IllegalArgumentException} if the {@code condition} is false. */
+    /**
+     * 检查实参
+     *
+     * @param condition 判断参数是否符合条件的结果
+     * @param format    异常信息模板
+     * @param args      异常信息参数
+     * @throws IllegalArgumentException 当条件不满足时抛出
+     */
     public static void checkArgument(boolean condition, String format, Object... args) {
         checkCondition(condition, () -> new IllegalArgumentException(String.format(format, args)));
     }
@@ -77,22 +101,46 @@ public class AssertTools {
     // #region - State
     // ================================
 
-    /** Throw {@link IllegalStateException} if the {@code condition} is false. */
+    /**
+     * 检查状态
+     *
+     * @param condition 判断状态是否符合条件的结果
+     * @throws IllegalStateException 当条件不满足时抛出
+     */
     public static void checkState(boolean condition) {
         checkCondition(condition, IllegalStateException::new);
     }
 
-    /** Throw {@link IllegalStateException} if the {@code condition} is false. */
+    /**
+     * 检查状态
+     *
+     * @param condition 判断状态是否符合条件的结果
+     * @param errMsg    异常信息
+     * @throws IllegalStateException 当条件不满足时抛出
+     */
     public static void checkState(boolean condition, @Nullable String errMsg) {
         checkCondition(condition, () -> new IllegalStateException(errMsg));
     }
 
-    /** Throw {@link IllegalStateException} if the {@code condition} is false. */
+    /**
+     * 检查状态
+     *
+     * @param condition       判断状态是否符合条件的结果
+     * @param messageSupplier 异常信息
+     * @throws IllegalStateException 当条件不满足时抛出
+     */
     public static void checkState(boolean condition, Supplier<String> messageSupplier) {
         checkCondition(condition, () -> new IllegalStateException(messageSupplier.get()));
     }
 
-    /** Throw {@link IllegalStateException} if the {@code condition} is false. */
+    /**
+     * 检查状态
+     *
+     * @param condition 判断状态是否符合条件的结果
+     * @param format    异常信息模板
+     * @param args      异常信息参数
+     * @throws IllegalStateException 当条件不满足时抛出
+     */
     public static void checkState(boolean condition, String format, Object... args) {
         checkCondition(condition, () -> new IllegalStateException(String.format(format, args)));
     }
@@ -105,22 +153,50 @@ public class AssertTools {
     // #region - NotNull
     // ================================
 
-    /** Throw {@link NullPointerException} if the {@code obj} is null. */
+    /**
+     * 判空
+     *
+     * @param <T> 入参类型
+     * @param obj 入参     *
+     * @throws NullPointerException 当 {@code obj} 为 {@code null} 时抛出
+     */
     public static <T> void checkNotNull(@Nullable T obj) {
         checkCondition(obj != null, NullPointerException::new);
     }
 
-    /** Throw {@link NullPointerException} if the {@code obj} is null. */
+    /**
+     * 判空
+     *
+     * @param <T>    入参类型
+     * @param obj    入参
+     * @param errMsg 异常信息     *
+     * @throws NullPointerException 当 {@code obj} 为 {@code null} 时抛出
+     */
     public static <T> void checkNotNull(@Nullable T obj, String errMsg) {
         checkCondition(obj != null, () -> new NullPointerException(errMsg));
     }
 
-    /** Throw {@link NullPointerException} if the {@code obj} is null. */
+    /**
+     * 判空
+     *
+     * @param <T>             入参类型
+     * @param obj             入参
+     * @param messageSupplier 异常信息     *
+     * @throws NullPointerException 当 {@code obj} 为 {@code null} 时抛出
+     */
     public static <T> void checkNotNull(@Nullable T obj, Supplier<String> messageSupplier) {
         checkCondition(obj != null, () -> new NullPointerException(messageSupplier.get()));
     }
 
-    /** Throw {@link NullPointerException} if the {@code obj} is null. */
+    /**
+     * 判空
+     *
+     * @param <T>    入参类型
+     * @param obj    入参
+     * @param format 异常信息模板
+     * @param args   异常信息参数
+     * @throws NullPointerException 当 {@code obj} 为 {@code null} 时抛出
+     */
     public static <T> void checkNotNull(@Nullable T obj, String format, Object... args) {
         checkCondition(obj != null, () -> new NullPointerException(String.format(format, args)));
     }
@@ -133,56 +209,120 @@ public class AssertTools {
     // #region - Exists
     // ================================
 
-    /** Throw {@link DataNotExistsException} if the {@code obj} is null. */
+    /**
+     * 检查数据是否存在
+     *
+     * @param <T> 入参类型
+     * @param obj 入参
+     * @return 如果 {@code obj} 存在，返回 {@code obj} 本身
+     * @throws DataNotExistsException 当 {@code obj} 不存在时抛出
+     */
     public static <T> T checkExists(@Nullable T obj)
             throws DataNotExistsException {
         checkCondition(Objects.nonNull(obj), DataNotExistsException::new);
         return obj;
     }
 
-    /** Throw {@link DataNotExistsException} if the {@code obj} is null. */
+    /**
+     * 检查数据是否存在
+     *
+     * @param <T> 入参类型
+     * @param obj 入参
+     * @param message 异常信息
+     * @return 如果 {@code obj} 存在，返回 {@code obj} 本身
+     * @throws DataNotExistsException 当 {@code obj} 不存在时抛出
+     */
     public static <T> T checkExists(@Nullable T obj, String message)
             throws DataNotExistsException {
         checkCondition(Objects.nonNull(obj), () -> new DataNotExistsException(message));
         return obj;
     }
 
-    /** Throw {@link DataNotExistsException} if the {@code obj} is null. */
+    /**
+     * 检查数据是否存在
+     *
+     * @param <T>             入参类型
+     * @param obj             入参
+     * @param messageSupplier 异常信息
+     * @return 如果 {@code obj} 存在，返回 {@code obj} 本身
+     * @throws DataNotExistsException 当 {@code obj} 不存在时抛出
+     */
     public static <T> T checkExists(@Nullable T obj, Supplier<String> messageSupplier)
             throws DataNotExistsException {
         checkCondition(Objects.nonNull(obj), () -> new DataNotExistsException(messageSupplier.get()));
         return obj;
     }
 
-    /** Throw {@link DataNotExistsException} if the {@code obj} is null. */
+    /**
+     * 检查数据是否存在
+     *
+     * @param <T>    入参类型
+     * @param obj    入参
+     * @param format 异常信息模板
+     * @param args   异常信息参数
+     * @return 如果 {@code obj} 存在，返回 {@code obj} 本身
+     * @throws DataNotExistsException 当 {@code obj} 不存在时抛出
+     */
     public static <T> T checkExists(@Nullable T obj, String format, Object... args)
             throws DataNotExistsException {
         checkCondition(Objects.nonNull(obj), () -> new DataNotExistsException(String.format(format, args)));
         return obj;
     }
 
-    /** Throw {@link DataNotExistsException} if the {@code optional} is present. */
+    /**
+     * 检查数据是否存在
+     *
+     * @param <T>      入参类型
+     * @param optional 入参
+     * @return 如果 {@code optional} 存在，返回 {@code optional} 包含的值
+     * @throws DataNotExistsException 当 {@code optional} 的值不存在时抛出
+     */
     public static <T> T checkExists(Optional<T> optional)
             throws DataNotExistsException {
         checkCondition(optional.isPresent(), DataNotExistsException::new);
         return optional.get();
     }
 
-    /** Throw {@link DataNotExistsException} if the {@code optional} is present. */
+    /**
+     * 检查数据是否存在
+     *
+     * @param <T>      入参类型
+     * @param optional 入参
+     * @param message  异常信息
+     * @return 如果 {@code optional} 存在，返回 {@code optional} 包含的值
+     * @throws DataNotExistsException 当 {@code optional} 的值不存在时抛出
+     */
     public static <T> T checkExists(Optional<T> optional, String message)
             throws DataNotExistsException {
         checkCondition(optional.isPresent(), () -> new DataNotExistsException(message));
         return optional.get();
     }
 
-    /** Throw {@link DataNotExistsException} if the {@code optional} is present. */
+    /**
+     * 检查数据是否存在
+     *
+     * @param <T>             入参类型
+     * @param optional        入参
+     * @param messageSupplier 异常信息
+     * @return 如果 {@code optional} 存在，返回 {@code optional} 包含的值
+     * @throws DataNotExistsException 当 {@code optional} 的值不存在时抛出
+     */
     public static <T> T checkExists(Optional<T> optional, Supplier<String> messageSupplier)
             throws DataNotExistsException {
         checkCondition(optional.isPresent(), () -> new DataNotExistsException(messageSupplier.get()));
         return optional.get();
     }
 
-    /** Throw {@link DataNotExistsException} if the {@code optional} is present. */
+    /**
+     * 检查数据是否存在
+     *
+     * @param <T>      入参类型
+     * @param optional 入参
+     * @param format   异常信息模板
+     * @param args     异常信息参数
+     * @return 如果 {@code optional} 存在，返回 {@code optional} 包含的值
+     * @throws DataNotExistsException 当 {@code optional} 的值不存在时抛出
+     */
     public static <T> T checkExists(Optional<T> optional, String format, Object... args)
             throws DataNotExistsException {
         checkCondition(optional.isPresent(), () -> new DataNotExistsException(String.format(format, args)));
@@ -197,78 +337,182 @@ public class AssertTools {
     // #region - AffectedRows
     // ================================
 
+    /**
+     * 当影响的数据量与预计不同时抛出 {@link DataOperationResultException}。
+     *
+     * @param expectedValue 预计的数量
+     * @param result        实际影响的数据量
+     */
     public static void checkAffectedRows(int expectedValue, int result) {
         checkAffectedRows(expectedValue, result,
                 "The number of rows affected is expected to be %d, but is: %d", expectedValue, result);
     }
 
+    /**
+     * 当影响的数据量与预计不同时抛出 {@link DataOperationResultException}。
+     *
+     * @param expectedValue 预计的数量
+     * @param result        实际影响的数据量
+     * @param message       异常信息
+     */
     public static void checkAffectedRows(int expectedValue, int result, @Nullable String message) {
         checkCondition(expectedValue == result, () -> new DataOperationResultException(message));
     }
 
+    /**
+     * 当影响的数据量与预计不同时抛出 {@link DataOperationResultException}。
+     *
+     * @param expectedValue   预计的数量
+     * @param result          实际影响的数据量
+     * @param messageSupplier 异常信息
+     */
     public static void checkAffectedRows(int expectedValue, int result,
             Supplier<String> messageSupplier) {
         checkCondition(expectedValue == result,
                 () -> new DataOperationResultException(messageSupplier.get()));
     }
 
+    /**
+     * 当影响的数据量与预计不同时抛出 {@link DataOperationResultException}。
+     *
+     * @param expectedValue 预计的数量
+     * @param result        实际影响的数据量
+     * @param format        异常信息模板
+     * @param args          异常信息参数
+     */
     public static void checkAffectedRows(int expectedValue, int result,
             String format, Object... args) {
         checkCondition(expectedValue == result,
                 () -> new DataOperationResultException(String.format(format, args)));
     }
 
+    /**
+     * 当影响的数据量与预计不同时抛出 {@link DataOperationResultException}。
+     *
+     * @param expectedValue 预计的数量
+     * @param result        实际影响的数据量
+     */
     public static void checkAffectedRows(long expectedValue, long result) {
         checkAffectedRows(expectedValue, result,
                 "The number of rows affected is expected to be %d, but is: %d", expectedValue, result);
     }
 
+    /**
+     * 当影响的数据量与预计不同时抛出 {@link DataOperationResultException}。
+     *
+     * @param expectedValue 预计的数量
+     * @param result        实际影响的数据量
+     * @param message       异常信息
+     */
     public static void checkAffectedRows(long expectedValue, long result, @Nullable String message) {
         checkCondition(expectedValue == result, () -> new DataOperationResultException(message));
     }
 
+    /**
+     * 当影响的数据量与预计不同时抛出 {@link DataOperationResultException}。
+     *
+     * @param expectedValue   预计的数量
+     * @param result          实际影响的数据量
+     * @param messageSupplier 异常信息
+     */
     public static void checkAffectedRows(long expectedValue, long result,
             Supplier<String> messageSupplier) {
         checkCondition(expectedValue == result,
                 () -> new DataOperationResultException(messageSupplier.get()));
     }
 
+    /**
+     * 当影响的数据量与预计不同时抛出 {@link DataOperationResultException}。
+     *
+     * @param expectedValue 预计的数量
+     * @param result        实际影响的数据量
+     * @param format        异常信息模板
+     * @param args          异常信息参数
+     */
     public static void checkAffectedRows(long expectedValue, long result,
             String format, Object... args) {
         checkCondition(expectedValue == result,
                 () -> new DataOperationResultException(String.format(format, args)));
     }
 
+    /**
+     * 当影响的数据量不为 1 时抛出 {@link DataOperationResultException}。
+     *
+     * @param result 实际影响的数据量
+     */
     public static void checkAffectedOneRow(int result) {
         checkAffectedRows(1, result,
                 () -> "The number of rows affected is expected to be 1, but is: " + result);
     }
 
+    /**
+     * 当影响的数据量不为 1 时抛出 {@link DataOperationResultException}。
+     *
+     * @param result  实际影响的数据量
+     * @param message 异常信息
+     */
     public static void checkAffectedOneRow(int result, String message) {
         checkAffectedRows(1, result, message);
     }
 
+    /**
+     * 当影响的数据量不为 1 时抛出 {@link DataOperationResultException}。
+     *
+     * @param result          实际影响的数据量
+     * @param messageSupplier 异常信息
+     */
     public static void checkAffectedOneRow(int result, Supplier<String> messageSupplier) {
         checkAffectedRows(1, result, messageSupplier);
     }
 
+    /**
+     * 当影响的数据量不为 1 时抛出 {@link DataOperationResultException}。
+     *
+     * @param result 实际影响的数据量
+     * @param format 异常信息模板
+     * @param args   异常信息参数
+     */
     public static void checkAffectedOneRow(int result, String format, Object... args) {
         checkAffectedRows(1, result, format, args);
     }
 
+    /**
+     * 当影响的数据量不为 1 时抛出 {@link DataOperationResultException}。
+     *
+     * @param result 实际影响的数据量
+     */
     public static void checkAffectedOneRow(long result) {
         checkAffectedRows(1L, result,
                 () -> "The number of rows affected is expected to be 1, but is: " + result);
     }
 
+    /**
+     * 当影响的数据量不为 1 时抛出 {@link DataOperationResultException}。
+     *
+     * @param result  实际影响的数据量
+     * @param message 异常信息
+     */
     public static void checkAffectedOneRow(long result, String message) {
         checkAffectedRows(1L, result, message);
     }
 
+    /**
+     * 当影响的数据量不为 1 时抛出 {@link DataOperationResultException}。
+     *
+     * @param result          实际影响的数据量
+     * @param messageSupplier 异常信息
+     */
     public static void checkAffectedOneRow(long result, Supplier<String> messageSupplier) {
         checkAffectedRows(1L, result, messageSupplier);
     }
 
+    /**
+     * 当影响的数据量不为 1 时抛出 {@link DataOperationResultException}。
+     *
+     * @param result 实际影响的数据量
+     * @param format 异常信息模板
+     * @param args   异常信息参数
+     */
     public static void checkAffectedOneRow(long result,
             String format, Object... args) {
         checkAffectedRows(1L, result, format, args);
@@ -282,6 +526,14 @@ public class AssertTools {
     // #region - Condition
     // ================================
 
+    /**
+     * 当条件不满足时抛出异常。
+     *
+     * @param <T>       异常类型
+     * @param condition 条件
+     * @param e         异常
+     * @throws T 当条件不满足时抛出异常
+     */
     public static <T extends Exception> void checkCondition(boolean condition, Supplier<T> e)
             throws T {
         if (!condition) {

src/main/java/xyz/zhouxy/plusone/commons/util/BigDecimals.java

@@ -35,34 +35,75 @@ import xyz.zhouxy.plusone.commons.annotation.StaticFactoryMethod;
  */
 public class BigDecimals {
 
+    /**
+     * 判断两个 {@code BigDecimal} 的值是否相等
+     *
+     * @param a 第一个 {@code BigDecimal}
+     * @param b 第二个 {@code BigDecimal}
+     * @return 当两个 {@code BigDecimal} 的值相等时返回 {@code true}
+     */
     public static boolean equalsValue(@Nullable BigDecimal a, @Nullable BigDecimal b) {
         return (a == b) || (a != null && b != null && a.compareTo(b) == 0);
     }
 
+    /**
+     * 判断两个 {@code BigDecimal} 的值 - 大于
+     *
+     * @param a 第一个 {@code BigDecimal}
+     * @param b 第二个 {@code BigDecimal}
+     * @return 当 {@code a} 大于 {@code b} 时返回 {@code true}
+     */
     public static boolean gt(BigDecimal a, BigDecimal b) {
         AssertTools.checkNotNull(a, "Parameter could not be null.");
         AssertTools.checkNotNull(b, "Parameter could not be null.");
         return (a != b) && (a.compareTo(b) > 0);
     }
 
+    /**
+     * 判断两个 {@code BigDecimal} 的值 - 大于等于
+     *
+     * @param a 第一个 {@code BigDecimal}
+     * @param b 第二个 {@code BigDecimal}
+     * @return 当 {@code a} 大于等于 {@code b} 时返回 {@code true}
+     */
     public static boolean ge(BigDecimal a, BigDecimal b) {
         AssertTools.checkNotNull(a, "Parameter could not be null.");
         AssertTools.checkNotNull(b, "Parameter could not be null.");
         return (a == b) || (a.compareTo(b) >= 0);
     }
 
+    /**
+     * 判断两个 {@code BigDecimal} 的值 - 小于
+     *
+     * @param a 第一个 {@code BigDecimal}
+     * @param b 第二个 {@code BigDecimal}
+     * @return 当 {@code a} 小于 {@code b} 时返回 {@code true}
+     */
     public static boolean lt(BigDecimal a, BigDecimal b) {
         AssertTools.checkNotNull(a, "Parameter could not be null.");
         AssertTools.checkNotNull(b, "Parameter could not be null.");
         return (a != b) && (a.compareTo(b) < 0);
     }
 
+    /**
+     * 判断两个 {@code BigDecimal} 的值 - 小于等于
+     *
+     * @param a 第一个 {@code BigDecimal}
+     * @param b 第二个 {@code BigDecimal}
+     * @return 当 {@code a} 小于等于 {@code b} 时返回 {@code true}
+     */
     public static boolean le(BigDecimal a, BigDecimal b) {
         AssertTools.checkNotNull(a, "Parameter could not be null.");
         AssertTools.checkNotNull(b, "Parameter could not be null.");
         return (a == b) || (a.compareTo(b) <= 0);
     }
 
+    /**
+     * 求和
+     *
+     * @param numbers {@code BigDecimal} 数组
+     * @return 求和结果
+     */
     public static BigDecimal sum(final BigDecimal... numbers) {
         if (ArrayTools.isNullOrEmpty(numbers)) {
             return BigDecimal.ZERO;
@@ -77,11 +118,23 @@ public class BigDecimals {
         return result;
     }
 
+    /**
+     * 将 {@code null} 转换为 {@link BigDecimal#ZERO}
+     *
+     * @param val BigDecimal 对象
+     * @return 如果 {@code val} 为 {@code null}，则返回 {@link BigDecimal#ZERO}，否则返回 {@code val}
+     */
     @Nonnull
     public static BigDecimal nullToZero(@Nullable final BigDecimal val) {
         return val != null ? val : BigDecimal.ZERO;
     }
 
+    /**
+     * 获取字符串所表示的数值转换为 {@code BigDecimal}
+     *
+     * @param val 表示数值的字符串
+     * @return {@code BigDecimal} 对象
+     */
     @StaticFactoryMethod(BigDecimal.class)
     public static BigDecimal of(@Nullable final String val) {
         return (StringTools.isNotBlank(val)) ? new BigDecimal(val) : BigDecimal.ZERO;

src/main/java/xyz/zhouxy/plusone/commons/util/DateTimeTools.java

@@ -702,18 +702,43 @@ public class DateTimeTools {
     // #region - start & end
     // ================================
 
+    /**
+     * 获取指定年份的开始日期
+     *
+     * @param year 年份
+     * @return 指定年份的开始日期
+     */
     public static LocalDate startDateOfYear(int year) {
         return LocalDate.ofYearDay(year, 1);
     }
 
+    /**
+     * 获取指定年份的结束日期
+     *
+     * @param year 年份
+     * @return 指定年份的结束日期
+     */
     public static LocalDate endDateOfYear(int year) {
         return LocalDate.of(year, 12, 31);
     }
 
+    /**
+     * 获取指定日期的第二天的开始时间
+     *
+     * @param date 日期
+     * @return 指定日期的第二天的开始时间
+     */
     public static LocalDateTime startOfNextDate(LocalDate date) {
         return date.plusDays(1L).atStartOfDay();
     }
 
+    /**
+     * 获取指定日期的第二天的开始时间
+     *
+     * @param date 日期
+     * @param zone 时区
+     * @return 指定日期的第二天的开始时间
+     */
     public static ZonedDateTime startOfNextDate(LocalDate date, ZoneId zone) {
         return date.plusDays(1L).atStartOfDay(zone);
     }
@@ -726,30 +751,72 @@ public class DateTimeTools {
     // #region - isFuture
     // ================================
 
+    /**
+     * 判断指定日期时间是否在将来
+     *
+     * @param date 日期时间
+     * @return 指定日期时间是否在将来
+     */
     public static boolean isFuture(Date date) {
         return date.after(new Date());
     }
 
-    public static boolean isFuture(Calendar date) {
+    /**
-        return date.after(Calendar.getInstance());
+     * 判断指定日期时间是否在将来
+     *
+     * @param calendar 日期时间
+     * @return 指定日期时间是否在将来
+     */
+    public static boolean isFuture(Calendar calendar) {
+        return calendar.after(Calendar.getInstance());
     }
 
+    /**
+     * 判断指定时刻是否在将来
+     *
+     * @param instant 时刻
+     * @return 指定时刻是否在将来
+     */
     public static boolean isFuture(Instant instant) {
         return instant.isAfter(Instant.now());
     }
 
+    /**
+     * 判断指定时间戳是否在将来
+     *
+     * @param timeMillis 时间戳
+     * @return 指定时间戳是否在将来
+     */
     public static boolean isFuture(long timeMillis) {
         return timeMillis > System.currentTimeMillis();
     }
 
+    /**
+     * 判断指定日期是否在将来
+     *
+     * @param date 日期
+     * @return 指定日期是否在将来
+     */
     public static boolean isFuture(LocalDate date) {
         return date.isAfter(LocalDate.now());
     }
 
+    /**
+     * 判断指定日期时间是否在将来
+     *
+     * @param dateTime 日期时间
+     * @return 指定日期时间是否在将来
+     */
     public static boolean isFuture(LocalDateTime dateTime) {
         return dateTime.isAfter(LocalDateTime.now());
     }
 
+    /**
+     * 判断指定日期时间是否在将来
+     *
+     * @param dateTime 日期时间
+     * @return 指定日期时间是否在将来
+     */
     public static boolean isFuture(ZonedDateTime dateTime) {
         return dateTime.isAfter(ZonedDateTime.now());
     }
@@ -762,30 +829,72 @@ public class DateTimeTools {
     // #region - isPast
     // ================================
 
+    /**
+     * 判断指定日期时间是否在过去
+     *
+     * @param date 日期时间
+     * @return 指定日期时间是否在过去
+     */
     public static boolean isPast(Date date) {
         return date.before(new Date());
     }
 
-    public static boolean isPast(Calendar date) {
+    /**
-        return date.before(Calendar.getInstance());
+     * 判断指定日期时间是否在过去
+     *
+     * @param calendar 日期时间
+     * @return 指定日期时间是否在过去
+     */
+    public static boolean isPast(Calendar calendar) {
+        return calendar.before(Calendar.getInstance());
     }
 
+    /**
+     * 判断指定时刻是否在过去
+     *
+     * @param instant 时刻
+     * @return 指定时刻是否在过去
+     */
     public static boolean isPast(Instant instant) {
         return instant.isBefore(Instant.now());
     }
 
+    /**
+     * 判断指定时间戳是否在过去
+     *
+     * @param timeMillis 时间戳
+     * @return 指定时间戳是否在过去
+     */
     public static boolean isPast(long timeMillis) {
         return timeMillis < System.currentTimeMillis();
     }
 
+    /**
+     * 判断指定日期是否在过去
+     *
+     * @param date 日期
+     * @return 指定日期是否在过去
+     */
     public static boolean isPast(LocalDate date) {
         return date.isBefore(LocalDate.now());
     }
 
+    /**
+     * 判断指定日期时间是否在过去
+     *
+     * @param dateTime 日期时间
+     * @return 指定日期时间是否在过去
+     */
     public static boolean isPast(LocalDateTime dateTime) {
         return dateTime.isBefore(LocalDateTime.now());
     }
 
+    /**
+     * 判断指定日期时间是否在过去
+     *
+     * @param dateTime 日期时间
+     * @return 指定日期时间是否在过去
+     */
     public static boolean isPast(ZonedDateTime dateTime) {
         return dateTime.isBefore(ZonedDateTime.now());
     }
@@ -798,14 +907,33 @@ public class DateTimeTools {
     // #region - others
     // ================================
 
+    /**
+     * 获取指定日期的时间范围
+     *
+     * @param date 日期
+     * @return 指定日期的时间范围
+     */
     public static Range<LocalDateTime> toDateTimeRange(LocalDate date) {
         return Range.closedOpen(date.atStartOfDay(), startOfNextDate(date));
     }
 
+    /**
+     * 获取指定日期的时间范围
+     *
+     * @param date 日期
+     * @param zone 时区
+     * @return 指定日期的时间范围
+     */
     public static Range<ZonedDateTime> toDateTimeRange(LocalDate date, ZoneId zone) {
         return Range.closedOpen(date.atStartOfDay(zone), startOfNextDate(date, zone));
     }
 
+    /**
+     * 判断指定年份是否为闰年
+     *
+     * @param year 年份
+     * @return 指定年份是否为闰年
+     */
     public static boolean isLeapYear(int year) {
         return IsoChronology.INSTANCE.isLeapYear(year);
     }
@@ -815,7 +943,7 @@ public class DateTimeTools {
     // ================================
 
     /**
-     * 私有构造方法，明确标识该常量类的作用。
+     * 私有构造方法
      */
     private DateTimeTools() {
         throw new IllegalStateException("Utility class");

src/main/java/xyz/zhouxy/plusone/commons/util/Enumeration.java

@@ -48,10 +48,20 @@ public abstract class Enumeration<T extends Enumeration<T>> // NOSONAR 暂不移
         this.name = name;
     }
 
+    /**
+     * 枚举整数码值
+     *
+     * @return 整数码值
+     */
     public final int getId() {
         return id;
     }
 
+    /**
+     * 枚举名称
+     *
+     * @return 枚举名称
+     */
     public final String getName() {
         return name;
     }
@@ -84,6 +94,9 @@ public abstract class Enumeration<T extends Enumeration<T>> // NOSONAR 暂不移
         return getClass().getSimpleName() + '(' + id + ":" + name + ')';
     }
 
+    /**
+     * 枚举值集合
+     */
     protected static final class ValueSet<T extends Enumeration<T>> {
         private final Map<Integer, T> valueMap;
 
@@ -91,6 +104,13 @@ public abstract class Enumeration<T extends Enumeration<T>> // NOSONAR 暂不移
             this.valueMap = valueMap;
         }
 
+        /**
+         * 创建枚举值集合
+         *
+         * @param <T>    枚举类型
+         * @param values 枚举值
+         * @return 枚举值集合
+         */
         @StaticFactoryMethod(ValueSet.class)
         public static <T extends Enumeration<T>> ValueSet<T> of(T[] values) {
             Map<Integer, T> temp = Arrays.stream(values)
@@ -98,11 +118,22 @@ public abstract class Enumeration<T extends Enumeration<T>> // NOSONAR 暂不移
             return new ValueSet<>(Collections.unmodifiableMap(temp));
         }
 
+        /**
+         * 根据整数码值获取枚举对象
+         *
+         * @param id 整数码
+         * @return 枚举对象
+         */
         public T get(int id) {
             AssertTools.checkArgument(this.valueMap.containsKey(id), "[%s] 对应的值不存在", id);
             return this.valueMap.get(id);
         }
 
+        /**
+         * 获取所有枚举对象
+         *
+         * @return 所有枚举对象
+         */
         public Collection<T> getValues() {
             return this.valueMap.values();
         }

src/main/java/xyz/zhouxy/plusone/commons/util/IdGenerator.java

@@ -36,18 +36,39 @@ public class IdGenerator {
 
     // ===== UUID =====
 
+    /**
+     * 生成 UUID
+     *
+     * @return UUID
+     */
     public static UUID newUuid() {
         return UUID.randomUUID();
     }
 
+    /**
+     * 生成 UUID 字符串
+     *
+     * @return UUID 字符串
+     */
     public static String uuidString() {
         return UUID.randomUUID().toString();
     }
 
+    /**
+     * 生成 UUID 字符串（无分隔符）
+     *
+     * @return UUID 字符串
+     */
     public static String simpleUuidString() {
         return toSimpleString(UUID.randomUUID());
     }
 
+    /**
+     * 生成 UUID 字符串（无分隔符）
+     *
+     * @param uuid UUID
+     * @return UUID 字符串
+     */
     public static String toSimpleString(UUID uuid) {
         AssertTools.checkArgument(Objects.nonNull(uuid));
         return (uuidDigits(uuid.getMostSignificantBits() >> 32, 8) +
@@ -67,11 +88,23 @@ public class IdGenerator {
 
     private static final Map<Long, IdWorker> snowflakePool = new ConcurrentHashMap<>();
 
+    /**
+     * 生成雪花ID
+     *
+     * @param workerId 工作机器ID
+     * @return 雪花ID
+     */
     public static long nextSnowflakeId(long workerId) {
         IdWorker generator = getSnowflakeIdGenerator(workerId);
         return generator.nextId();
     }
 
+    /**
+     * 获取雪花ID生成器
+     *
+     * @param workerId 工作机器ID
+     * @return {@code IdWorker} 对象。来自 Seata 的修改版雪花ID生成器。
+     */
     public static IdWorker getSnowflakeIdGenerator(long workerId) {
         return snowflakePool.computeIfAbsent(workerId, wid -> new IdWorker(workerId));
     }

src/main/java/xyz/zhouxy/plusone/commons/util/Numbers.java

@@ -23,7 +23,7 @@ import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 
 /**
- * Numbers
+ * 数字工具类
  *
  * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
  */
@@ -31,6 +31,12 @@ public class Numbers {
 
     // #region - sum
 
+    /**
+     * 求和
+     *
+     * @param numbers 数据数组
+     * @return 求和结果
+     */
     public static int sum(final short... numbers) {
         int result = 0;
         for (short number : numbers) {
@@ -39,6 +45,12 @@ public class Numbers {
         return result;
     }
 
+    /**
+     * 求和
+     *
+     * @param numbers 数据数组
+     * @return 求和结果
+     */
     public static long sum(final int... numbers) {
         long result = 0L;
         for (int number : numbers) {
@@ -47,6 +59,12 @@ public class Numbers {
         return result;
     }
 
+    /**
+     * 求和
+     *
+     * @param numbers 数据数组
+     * @return 求和结果
+     */
     public static long sum(final long... numbers) {
         long result = 0L;
         for (long number : numbers) {
@@ -55,6 +73,12 @@ public class Numbers {
         return result;
     }
 
+    /**
+     * 求和
+     *
+     * @param numbers 数据数组
+     * @return 求和结果
+     */
     public static double sum(final float... numbers) {
         double result = 0.00;
         for (float number : numbers) {
@@ -63,6 +87,12 @@ public class Numbers {
         return result;
     }
 
+    /**
+     * 求和
+     *
+     * @param numbers 数据数组
+     * @return 求和结果
+     */
     public static double sum(final double... numbers) {
         double result = 0.00;
         for (double number : numbers) {
@@ -71,6 +101,12 @@ public class Numbers {
         return result;
     }
 
+    /**
+     * 求和
+     *
+     * @param numbers 数据数组
+     * @return 求和结果
+     */
     public static BigInteger sum(final BigInteger... numbers) {
         if (ArrayTools.isNullOrEmpty(numbers)) {
             return BigInteger.ZERO;
@@ -85,6 +121,12 @@ public class Numbers {
         return result;
     }
 
+    /**
+     * 求和
+     *
+     * @param numbers 数据数组
+     * @return 求和结果
+     */
     public static BigDecimal sum(final BigDecimal... numbers) {
         return BigDecimals.sum(numbers);
     }
@@ -93,35 +135,83 @@ public class Numbers {
 
     // #region - nullToZero
 
+    /**
+     * 将 {@code null} 转换为 {@code 0}
+     *
+     * @param val 待转换的值
+     * @return 如果 {@code val} 不为 {@code null}，则返回该值；如果值为 {@code null}，则返回 {@code 0}
+     */
     public static byte nullToZero(@Nullable final Byte val) {
         return val != null ? val : 0;
     }
 
+    /**
+     * 将 {@code null} 转换为 {@code 0}
+     *
+     * @param val 待转换的值
+     * @return 如果 {@code val} 不为 {@code null}，则返回该值；如果值为 {@code null}，则返回 {@code 0}
+     */
     public static short nullToZero(@Nullable final Short val) {
         return val != null ? val : 0;
     }
 
+    /**
+     * 将 {@code null} 转换为 {@code 0}
+     *
+     * @param val 待转换的值
+     * @return 如果 {@code val} 不为 {@code null}，则返回该值；如果值为 {@code null}，则返回 {@code 0}
+     */
     public static int nullToZero(@Nullable final Integer val) {
         return val != null ? val : 0;
     }
 
+    /**
+     * 将 {@code null} 转换为 {@code 0}
+     *
+     * @param val 待转换的值
+     * @return 如果 {@code val} 不为 {@code null}，则返回该值；如果值为 {@code null}，则返回 {@code 0}
+     */
     public static long nullToZero(@Nullable final Long val) {
         return val != null ? val : 0L;
     }
 
+    /**
+     * 将 {@code null} 转换为 {@code 0}
+     *
+     * @param val 待转换的值
+     * @return 如果 {@code val} 不为 {@code null}，则返回该值；如果值为 {@code null}，则返回 {@code 0}
+     */
     public static float nullToZero(@Nullable final Float val) {
         return val != null ? val : 0.0F;
     }
 
+    /**
+     * 将 {@code null} 转换为 {@code 0}
+     *
+     * @param val 待转换的值
+     * @return 如果 {@code val} 不为 {@code null}，则返回该值；如果值为 {@code null}，则返回 {@code 0}
+     */
     public static double nullToZero(@Nullable final Double val) {
         return val != null ? val : 0.0;
     }
 
+    /**
+     * 将 {@code null} 转换为 {@code 0}
+     *
+     * @param val 待转换的值
+     * @return 如果 {@code val} 不为 {@code null}，则返回该值；如果值为 {@code null}，则返回 {@code 0}
+     */
     @Nonnull
     public static BigInteger nullToZero(@Nullable final BigInteger val) {
         return val != null ? val : BigInteger.ZERO;
     }
 
+    /**
+     * 将 {@code null} 转换为 {@code 0}
+     *
+     * @param val 待转换的值
+     * @return 如果 {@code val} 不为 {@code null}，则返回该值；如果值为 {@code null}，则返回 {@code 0}
+     */
     @Nonnull
     public static BigDecimal nullToZero(@Nullable final BigDecimal val) {
         return BigDecimals.nullToZero(val);

src/main/java/xyz/zhouxy/plusone/commons/util/OptionalTools.java

@@ -134,16 +134,34 @@ public class OptionalTools {
         return optionalObj.orElse(null);
     }
 
+    /**
+     * 将 {@link OptionalInt} 转为 {@link Integer}
+     *
+     * @param optionalObj optional 对象
+     * @return {@link Integer} 对象。如果 {@code OptionalInt} 的值缺失，返回 {@code null}。
+     */
     @Beta
     public static Integer toInteger(OptionalInt optionalObj) {
         return optionalObj.isPresent() ? optionalObj.getAsInt() : null;
     }
 
+    /**
+     * 将 {@link OptionalLong} 转为 {@link Long}
+     *
+     * @param optionalObj optional 对象
+     * @return {@link Long} 对象。如果 {@code OptionalLong} 的值缺失，返回 {@code null}。
+     */
     @Beta
     public static Long toLong(OptionalLong optionalObj) {
         return optionalObj.isPresent() ? optionalObj.getAsLong() : null;
     }
 
+    /**
+     * 将 {@link OptionalDouble} 转为 {@link Double}
+     *
+     * @param optionalObj optional 对象
+     * @return {@link Double} 对象。如果 {@code OptionalDouble} 的值缺失，返回 {@code null}。
+     */
     @Beta
     public static Double toDouble(OptionalDouble optionalObj) {
         return optionalObj.isPresent() ? optionalObj.getAsDouble() : null;

src/main/java/xyz/zhouxy/plusone/commons/util/RegexTools.java

@@ -326,12 +326,26 @@ public final class RegexTools {
         return input != null && pattern.matcher(input).matches();
     }
 
+    /**
+     * 判断 {@code input} 是否匹配至少一个正则。
+     *
+     * @param input    输入
+     * @param patterns 正则表达式
+     * @return 判断结果
+     */
     private static boolean matchesOneInternal(@Nullable final CharSequence input, final Pattern[] patterns) {
         return input != null
                 && Arrays.stream(patterns)
                         .anyMatch(pattern -> pattern.matcher(input).matches());
     }
 
+    /**
+     * 判断 {@code input} 是否匹配全部正则。
+     *
+     * @param input    输入
+     * @param patterns 正则表达式
+     * @return 判断结果
+     */
     private static boolean matchesAllInternal(@Nullable final CharSequence input, final Pattern[] patterns) {
         return input != null
                 && Arrays.stream(patterns)

src/main/java/xyz/zhouxy/plusone/commons/util/TreeBuilder.java

@@ -39,11 +39,26 @@ public class TreeBuilder<T, TSubTree extends T, TIdentity> {
     private final BiConsumer<TSubTree, T> addChildMethod;
     private final Comparator<? super T> defaultComparator;
 
+    /**
+     * 构造一个 {@code TreeBuilder}。不指定用于排序的 {@code Comparator}。
+     *
+     * @param identityGetter       从节点中获取其标识的逻辑
+     * @param parentIdentityGetter 获取父节点标识的逻辑
+     * @param addChild             添加子节点的逻辑
+     */
     public TreeBuilder(Function<T, TIdentity> identityGetter, Function<T, Optional<TIdentity>> parentIdentityGetter,
             BiConsumer<TSubTree, T> addChild) {
         this(identityGetter, parentIdentityGetter, addChild, null);
     }
 
+    /**
+     * 构造一个 {@code TreeBuilder}。
+     *
+     * @param identityGetter       从节点中获取其标识的逻辑
+     * @param parentIdentityGetter 获取父节点标识的逻辑
+     * @param addChild             添加子节点的逻辑
+     * @param defaultComparator    默认的 {@code Comparator}，用于排序
+     */
     public TreeBuilder(Function<T, TIdentity> identityGetter, Function<T, Optional<TIdentity>> parentIdentityGetter,
             BiConsumer<TSubTree, T> addChild, @Nullable Comparator<? super T> defaultComparator) {
         this.identityGetter = identityGetter;