docs: 完善文档注释

src/main/java/xyz/zhouxy/jdbc/DefaultBeanRowMapper.java

@@ -54,8 +54,8 @@ import xyz.zhouxy.plusone.commons.annotation.StaticFactoryMethod;
  * <li>JavaBean 属性仅支持引用类型，不支持基本数据类型。</li>
  * <li>实际使用中还是建议针对目标类型自定义 {@link RowMapper}。</li>
  * </ul>
- * </p>
+
- * @author ZhouXY
+* @author ZhouXY
  * @since 1.0.0
  */
 public class DefaultBeanRowMapper<T> implements RowMapper<T> {

src/main/java/xyz/zhouxy/jdbc/JdbcOperationSupport.java

@@ -177,7 +177,7 @@ class JdbcOperationSupport {
      * @param rowMapper 行数据映射逻辑
      *
      * @return generated keys
-     * @throws SQLException 执行 SQL 遇到异常情况将抛出
+     * @throws SQLException 数据库执行异常
      */
     static <T> List<T> updateAndReturnKeys(Connection conn, String sql, Object[] params, RowMapper<T> rowMapper)
             throws SQLException {

src/main/java/xyz/zhouxy/jdbc/JdbcOperations.java

@@ -42,9 +42,13 @@ public interface JdbcOperations {
     /**
      * 执行查询，并按照自定义处理逻辑对结果进行处理，将结果转换为指定类型并返回
      *
+     * @param <T>           返回结果类型
      * @param sql           SQL
      * @param params        参数
      * @param resultHandler 结果处理器，用于处理 {@link ResultSet}
+     *
+     * @return 查询结果
+     * @throws SQLException SQL异常
      */
     <T> T query(String sql, Object[] params, ResultHandler<T> resultHandler)
             throws SQLException;
@@ -52,8 +56,12 @@ public interface JdbcOperations {
     /**
      * 执行查询，并按照自定义处理逻辑对结果进行处理，将结果转换为指定类型并返回
      *
+     * @param <T>           返回结果类型
      * @param sql           SQL
      * @param resultHandler 结果处理器，用于处理 {@link ResultSet}
+     *
+     * @return 查询结果
+     * @throws SQLException SQL异常
      */
     default <T> T query(String sql, ResultHandler<T> resultHandler)
             throws SQLException {
@@ -67,9 +75,13 @@ public interface JdbcOperations {
     /**
      * 执行查询，将查询结果的每一行数据按照指定逻辑进行处理，返回结果列表
      *
+     * @param <T>       返回结果列表中每一行数据的类型
      * @param sql       SQL
      * @param params    参数
      * @param rowMapper {@link ResultSet} 中每一行的数据的处理逻辑
+     *
+     * @return 查询结果列表
+     * @throws SQLException SQL 异常
      */
     <T> List<T> queryList(String sql, Object[] params, RowMapper<T> rowMapper)
             throws SQLException;
@@ -77,9 +89,13 @@ public interface JdbcOperations {
     /**
      * 执行查询，返回结果映射为指定的类型。当结果为单列时使用
      *
+     * @param <T>    目标类型
      * @param sql    SQL
      * @param params 参数
-     * @param clazz  将结果映射为指定的类型
+     * @param clazz  目标类型
+     *
+     * @return 映射结果。如果查询结果为空，则返回空列表
+     * @throws SQLException SQL异常
      */
     <T> List<T> queryList(String sql, Object[] params, Class<T> clazz)
             throws SQLException;
@@ -89,6 +105,9 @@ public interface JdbcOperations {
      *
      * @param sql    SQL
      * @param params 参数列表
+     *
+     * @return 结果列表
+     * @throws SQLException SQL 异常
      */
     List<Map<String, Object>> queryList(String sql, Object[] params)
             throws SQLException;
@@ -96,8 +115,12 @@ public interface JdbcOperations {
     /**
      * 执行查询，将查询结果的每一行数据按照指定逻辑进行处理，返回结果列表
      *
+     * @param <T>       目标类型
      * @param sql       SQL
      * @param rowMapper {@link ResultSet} 中每一行的数据的处理逻辑
+     *
+     * @return 结果列表
+     * @throws SQLException SQL 异常
      */
     default <T> List<T> queryList(String sql, RowMapper<T> rowMapper)
             throws SQLException {
@@ -107,8 +130,12 @@ public interface JdbcOperations {
     /**
      * 执行查询，返回结果映射为指定的类型。当结果为单列时使用
      *
+     * @param <T>   目标类型
      * @param sql   SQL
      * @param clazz 将结果映射为指定的类型
+     *
+     * @return 查询结果
+     * @throws SQLException SQL 异常
      */
     default <T> List<T> queryList(String sql, Class<T> clazz)
             throws SQLException {
@@ -119,6 +146,9 @@ public interface JdbcOperations {
      * 执行查询，每一行数据映射为 {@code Map<String, Object>}，返回结果列表
      *
      * @param sql SQL
+     *
+     * @return 结果列表
+     * @throws SQLException SQL 异常
      */
     default List<Map<String, Object>> queryList(String sql)
             throws SQLException {
@@ -132,9 +162,13 @@ public interface JdbcOperations {
     /**
      * 执行查询，将查询结果的第一行数据按照指定逻辑进行处理，返回 {@link Optional}
      *
+     * @param <T>       目标类型
      * @param sql       SQL
      * @param params    参数
      * @param rowMapper {@link ResultSet} 中每一行的数据的处理逻辑
+     *
+     * @return 查询结果
+     * @throws SQLException SQL 异常
      */
     <T> Optional<T> queryFirst(String sql, Object[] params, RowMapper<T> rowMapper)
             throws SQLException;
@@ -146,15 +180,21 @@ public interface JdbcOperations {
      * @param sql    SQL
      * @param params 参数
      * @param clazz  目标类型
+     *
+     * @return 查询结果
+     * @throws SQLException SQL 异常
      */
     <T> Optional<T> queryFirst(String sql, Object[] params, Class<T> clazz)
             throws SQLException;
 
     /**
-     * 执行查询，将第一行数据转为 Map<String, Object>
+     * 执行查询，将第一行数据转为 Map&lt;String, Object&gt;
      *
      * @param sql    SQL
      * @param params 参数
+     *
+     * @return 查询结果
+     * @throws SQLException SQL 异常
      */
     Optional<Map<String, Object>> queryFirst(String sql, Object[] params)
             throws SQLException;
@@ -162,8 +202,12 @@ public interface JdbcOperations {
     /**
      * 执行查询，将查询结果的第一行数据按照指定逻辑进行处理，返回 {@link Optional}
      *
+     * @param <T>       目标类型
      * @param sql       SQL
      * @param rowMapper {@link ResultSet} 中每一行的数据的处理逻辑
+     *
+     * @return 查询结果
+     * @throws SQLException SQL 异常
      */
     default <T> Optional<T> queryFirst(String sql, RowMapper<T> rowMapper)
             throws SQLException {
@@ -176,6 +220,9 @@ public interface JdbcOperations {
      * @param <T>   目标类型
      * @param sql   SQL
      * @param clazz 目标类型
+     *
+     * @return 第一行第一列的值，如果查询结果为空，则返回 {@code Optional#empty()}
+     * @throws SQLException SQL 异常
      */
     default <T> Optional<T> queryFirst(String sql, Class<T> clazz)
             throws SQLException {
@@ -183,9 +230,12 @@ public interface JdbcOperations {
     }
 
     /**
-     * 执行查询，将第一行数据转为 Map<String, Object>
+     * 执行查询，将第一行数据转为 Map&lt;String, Object&gt;
      *
      * @param sql SQL
+     *
+     * @return 查询结果
+     * @throws SQLException SQL 异常
      */
     default Optional<Map<String, Object>> queryFirst(String sql)
             throws SQLException {
@@ -195,10 +245,10 @@ public interface JdbcOperations {
     /**
      * 查询第一行第一列并转换为 boolean
      *
-     * <p>
-     * <b>注：如果查询结果为空，则返回 {@code false}。</b>
-     *
      * @param sql SQL
+     *
+     * @return 查询结果。如果查询结果为空，则返回 {@code false}。
+     * @throws SQLException SQL 异常
      */
     default boolean queryBoolean(String sql)
             throws SQLException {
@@ -208,10 +258,12 @@ public interface JdbcOperations {
     /**
      * 查询第一行第一列并转换为 boolean
      *
-     * <p>
-     * <b>注：如果查询结果为空，则返回 {@code false}。</b>
-     *
      * @param sql SQL
+     * @param params 参数
+     *
+     * @return 查询结果。如果查询结果为空，则返回 {@code false}
+     *
+     * @throws SQLException SQL 异常
      */
     boolean queryBoolean(String sql, Object[] params)
             throws SQLException;
@@ -226,6 +278,7 @@ public interface JdbcOperations {
      * @param sql    要执行的 SQL
      * @param params 参数
      * @return 更新记录数
+     * @throws SQLException SQL 异常
      */
     int update(String sql, Object[] params)
             throws SQLException;
@@ -235,6 +288,8 @@ public interface JdbcOperations {
      *
      * @param sql 要执行的 SQL
      * @return 更新记录数
+     *
+     * @throws SQLException 数据库执行异常
      */
     default int update(String sql)
             throws SQLException {
@@ -248,8 +303,10 @@ public interface JdbcOperations {
      * @param params    参数
      * @param rowMapper 行数据映射逻辑
      *
+     * @param <T>       映射结果类型
+     *
      * @return generated keys
-     * @throws SQLException 执行 SQL 遇到异常情况将抛出
+     * @throws SQLException 数据库执行异常
      */
     <T> List<T> updateAndReturnKeys(String sql, Object[] params, RowMapper<T> rowMapper)
             throws SQLException;
@@ -260,8 +317,10 @@ public interface JdbcOperations {
      * @param sql       要执行的 SQL
      * @param rowMapper 行数据映射逻辑
      *
+     * @param <T>       映射结果类型
+     *
      * @return generated keys
-     * @throws SQLException 执行 SQL 遇到异常情况将抛出
+     * @throws SQLException 数据库执行异常
      */
     default <T> List<T> updateAndReturnKeys(String sql, RowMapper<T> rowMapper)
             throws SQLException {
@@ -280,6 +339,9 @@ public interface JdbcOperations {
      * @param sql       SQL 语句
      * @param params    参数列表
      * @param batchSize 每次批量更新的数据量
+     *
+     * @return 批量更新的结果
+     * @throws SQLException SQL 异常
      */
     BatchUpdateResult batchUpdate(String sql, @Nullable Collection<Object[]> params, int batchSize)
             throws SQLException;
@@ -296,6 +358,9 @@ public interface JdbcOperations {
      * @param quietly    静默分批更新。
      *                   如果 {@code quietly} 为 {@code true}，分批更新过程中发生异常不中断操作；
      *                   如果 {@code quietly} 为 {@code false}，分批更新过程中发生异常即中断操作，并返回结果。
+     *
+     * @return 批次更新结果
+     * @throws SQLException 数据库执行异常
      */
     BatchUpdateResult batchUpdate(String sql, @Nullable Collection<Object[]> params,
                             int batchSize, boolean quietly)

src/main/java/xyz/zhouxy/jdbc/ResultHandler.java

@@ -34,6 +34,11 @@ public interface ResultHandler<T> {
 
     /**
      * 将 {@link ResultSet} 转换为指定类型的对象
+     *
+     * @param resultSet {@link ResultSet}
+     * @return 转换后的对象
+     *
+     * @throws SQLException 数据库执行异常
      */
     T handle(ResultSet resultSet) throws SQLException;
 }

src/main/java/xyz/zhouxy/jdbc/RowMapper.java

@@ -53,12 +53,29 @@ public interface RowMapper<T> {
         return result;
     };
 
-    /** 默认实现的将 {@link ResultSet} 转换为 Java Bean 的 {@link RowMapper}。 */
+    /**
+     * 默认实现的将 {@link ResultSet} 转换为 Java Bean 的 {@link RowMapper}。
+     *
+     * @param beanType Java Bean 的类型
+     * @param <T> Java Bean 的类型
+     *
+     * @return {@link DefaultBeanRowMapper}
+     * @throws SQLException 如果创建 {@link DefaultBeanRowMapper} 失败
+     */
     static <T> RowMapper<T> beanRowMapper(Class<T> beanType) throws SQLException {
         return DefaultBeanRowMapper.of(beanType);
     }
 
-    /** 默认实现的将 {@link ResultSet} 转换为 Java Bean 的 {@link RowMapper}。 */
+    /**
+     * 默认实现的将 {@link ResultSet} 转换为 Java Bean 的 {@link RowMapper}。
+     *
+     * @param beanType Java Bean 的类型
+     * @param propertyColMap Java Bean 属性名与数据库列名的映射关系
+     * @param <T> Java Bean 的类型
+     *
+     * @return {@link DefaultBeanRowMapper}
+     * @throws SQLException 如果创建 {@link DefaultBeanRowMapper} 失败
+     */
     static <T> RowMapper<T> beanRowMapper(Class<T> beanType, Map<String, String> propertyColMap)
             throws SQLException {
         return DefaultBeanRowMapper.of(beanType, propertyColMap);