From e4cba2c8d8591964e76bf48dcfbd0b68f097fa45 Mon Sep 17 00:00:00 2001 From: Nathan Xu Date: Thu, 21 Nov 2024 18:44:46 -0500 Subject: [PATCH] improve some Javadocs in sql package (#9228) * improve some Javadocs in sql package --------- Co-authored-by: nathan.xu Co-authored-by: Gavin King --- .../main/java/org/hibernate/sql/ForUpdateFragment.java | 2 +- .../src/main/java/org/hibernate/sql/Template.java | 4 ++-- .../src/main/java/org/hibernate/sql/ast/Clause.java | 8 ++------ .../main/java/org/hibernate/sql/ast/SqlAstJoinType.java | 2 +- .../main/java/org/hibernate/sql/ast/SqlAstTranslator.java | 4 ++-- .../hibernate/sql/ast/spi/AbstractSqlAstTranslator.java | 2 +- .../org/hibernate/sql/ast/spi/SqlAstCreationContext.java | 2 +- .../java/org/hibernate/sql/exec/spi/JdbcLockStrategy.java | 2 +- .../sql/exec/spi/JdbcOperationQueryAnonBlock.java | 2 +- .../results/internal/NavigablePathMapToInitializer.java | 8 +++++--- .../hibernate/sql/results/spi/ListResultsConsumer.java | 4 ++-- .../java/org/hibernate/sql/results/spi/RowReader.java | 4 ++-- 12 files changed, 21 insertions(+), 23 deletions(-) diff --git a/hibernate-core/src/main/java/org/hibernate/sql/ForUpdateFragment.java b/hibernate-core/src/main/java/org/hibernate/sql/ForUpdateFragment.java index 6f034a20d8..ab048a4fd4 100644 --- a/hibernate-core/src/main/java/org/hibernate/sql/ForUpdateFragment.java +++ b/hibernate-core/src/main/java/org/hibernate/sql/ForUpdateFragment.java @@ -14,7 +14,7 @@ import org.hibernate.dialect.RowLockStrategy; import org.hibernate.internal.util.StringHelper; /** - * A SQL {FOR UPDATE} clause. + * A SQL {@code FOR UPDATE} clause. * * @author Gavin King */ diff --git a/hibernate-core/src/main/java/org/hibernate/sql/Template.java b/hibernate-core/src/main/java/org/hibernate/sql/Template.java index 2be9d04f1c..23d9e4a8ed 100644 --- a/hibernate-core/src/main/java/org/hibernate/sql/Template.java +++ b/hibernate-core/src/main/java/org/hibernate/sql/Template.java @@ -23,12 +23,12 @@ import static org.hibernate.internal.util.StringHelper.WHITESPACE; * should be written in the native SQL dialect of the target database, * with the following special exceptions: *
    - *
  • any backtick-quoted identifiers, for example {@code `hello`}, + *
  • any backtick-quoted identifier, for example {@code `hello`}, * is interpreted as a quoted identifier and re-quoted using the * {@linkplain Dialect#quote native quoted identifier syntax} of * the database, and
    • *
  • the literal identifiers {@code true} and {@code false} are - * interpreted are literal boolean values, and replaced with + * interpreted as literal boolean values, and replaced with * {@linkplain Dialect#toBooleanValueString dialect-specific * literal values}. *
    • diff --git a/hibernate-core/src/main/java/org/hibernate/sql/ast/Clause.java b/hibernate-core/src/main/java/org/hibernate/sql/ast/Clause.java index ccfda72b1a..127375063b 100644 --- a/hibernate-core/src/main/java/org/hibernate/sql/ast/Clause.java +++ b/hibernate-core/src/main/java/org/hibernate/sql/ast/Clause.java @@ -39,9 +39,8 @@ public enum Clause { SET_EXPRESSION, /** - * Not used in 5.x. Intended for use in 6+ as indicator - * of processing predicates (where clause) that occur in a - * delete + * Used as indicator of processing predicates (where clause) + * that occur in a delete */ DELETE, MERGE, @@ -64,9 +63,6 @@ public enum Clause { CONFLICT, CALL, - /** - * Again, not used in 5.x. Used in 6+ - */ IRRELEVANT } diff --git a/hibernate-core/src/main/java/org/hibernate/sql/ast/SqlAstJoinType.java b/hibernate-core/src/main/java/org/hibernate/sql/ast/SqlAstJoinType.java index c7e88c3663..53b06335dc 100644 --- a/hibernate-core/src/main/java/org/hibernate/sql/ast/SqlAstJoinType.java +++ b/hibernate-core/src/main/java/org/hibernate/sql/ast/SqlAstJoinType.java @@ -24,7 +24,7 @@ public enum SqlAstJoinType { RIGHT( "right " ), /** - * Represents a cross join (aka a cartesian product). + * Represents a cross join (that is, a Cartesian product). */ CROSS( "cross " ), diff --git a/hibernate-core/src/main/java/org/hibernate/sql/ast/SqlAstTranslator.java b/hibernate-core/src/main/java/org/hibernate/sql/ast/SqlAstTranslator.java index 72997846cb..5f3ba57f3d 100644 --- a/hibernate-core/src/main/java/org/hibernate/sql/ast/SqlAstTranslator.java +++ b/hibernate-core/src/main/java/org/hibernate/sql/ast/SqlAstTranslator.java @@ -57,8 +57,8 @@ public interface SqlAstTranslator extends SqlAstWalker Stack getCurrentClauseStack(); /** - * Not the best spot for this. Its the table names collected while walking the SQL AST. - * Its ok here because the translator is consider a one-time-use. It just needs to be called + * Not the best spot for this. Returns the table names collected while walking the SQL AST. + * It's ok here because the translator is consider a one-time-use. It just needs to be called * after translation. * * A better option is probably to have "translation" objects that expose the affected table-names. diff --git a/hibernate-core/src/main/java/org/hibernate/sql/ast/spi/AbstractSqlAstTranslator.java b/hibernate-core/src/main/java/org/hibernate/sql/ast/spi/AbstractSqlAstTranslator.java index 85d5710bae..516ab521f2 100644 --- a/hibernate-core/src/main/java/org/hibernate/sql/ast/spi/AbstractSqlAstTranslator.java +++ b/hibernate-core/src/main/java/org/hibernate/sql/ast/spi/AbstractSqlAstTranslator.java @@ -246,7 +246,7 @@ public abstract class AbstractSqlAstTranslator implemen /** * When emulating the recursive WITH clause subclauses SEARCH and CYCLE, - * we need to build a string path and some database like MySQL require that + * we need to build a string path and some databases like MySQL require that * we cast the expression to a char with certain size. * To estimate the size, we need to assume a certain max recursion depth. */ diff --git a/hibernate-core/src/main/java/org/hibernate/sql/ast/spi/SqlAstCreationContext.java b/hibernate-core/src/main/java/org/hibernate/sql/ast/spi/SqlAstCreationContext.java index 6f4250c868..19401dde2c 100644 --- a/hibernate-core/src/main/java/org/hibernate/sql/ast/spi/SqlAstCreationContext.java +++ b/hibernate-core/src/main/java/org/hibernate/sql/ast/spi/SqlAstCreationContext.java @@ -10,7 +10,7 @@ import org.hibernate.query.BindingContext; /** * The "context" in which creation of SQL AST occurs. Provides - * access to generally needed when creating SQL AST nodes + * access to stuff generally needed when creating SQL AST nodes * * @author Steve Ebersole */ diff --git a/hibernate-core/src/main/java/org/hibernate/sql/exec/spi/JdbcLockStrategy.java b/hibernate-core/src/main/java/org/hibernate/sql/exec/spi/JdbcLockStrategy.java index d5cb85ea73..3f866d89df 100644 --- a/hibernate-core/src/main/java/org/hibernate/sql/exec/spi/JdbcLockStrategy.java +++ b/hibernate-core/src/main/java/org/hibernate/sql/exec/spi/JdbcLockStrategy.java @@ -12,7 +12,7 @@ package org.hibernate.sql.exec.spi; public enum JdbcLockStrategy { /** - * Use a dialect specific check to determine how to apply locks. + * Use a dialect-specific check to determine how to apply locks. */ AUTO, /** diff --git a/hibernate-core/src/main/java/org/hibernate/sql/exec/spi/JdbcOperationQueryAnonBlock.java b/hibernate-core/src/main/java/org/hibernate/sql/exec/spi/JdbcOperationQueryAnonBlock.java index 8ad01e3d9a..3025bd54cb 100644 --- a/hibernate-core/src/main/java/org/hibernate/sql/exec/spi/JdbcOperationQueryAnonBlock.java +++ b/hibernate-core/src/main/java/org/hibernate/sql/exec/spi/JdbcOperationQueryAnonBlock.java @@ -8,7 +8,7 @@ import org.hibernate.sql.results.jdbc.spi.JdbcValuesMappingProducer; /** * An anonymous call block (sometimes called an anonymous procedure) to be executed - * on the database. The format of this various by database, but it is essentially an + * on the database. The format of this varies by database, but it is essentially an * unnamed procedure without OUT, INOUT or REF_CURSOR type parameters * * @author Steve Ebersole diff --git a/hibernate-core/src/main/java/org/hibernate/sql/results/internal/NavigablePathMapToInitializer.java b/hibernate-core/src/main/java/org/hibernate/sql/results/internal/NavigablePathMapToInitializer.java index d4dcb03441..7e41093c27 100644 --- a/hibernate-core/src/main/java/org/hibernate/sql/results/internal/NavigablePathMapToInitializer.java +++ b/hibernate-core/src/main/java/org/hibernate/sql/results/internal/NavigablePathMapToInitializer.java @@ -15,10 +15,12 @@ import org.hibernate.sql.results.graph.Initializer; /** * This is in all practical terms a {@code Map} - * but wrapping an HashMap so to keep the client code readable as we need + * but wrapping a {@code HashMap} to keep the client code readable as we need * to: - * a) have a way to log all initializers - * b) prevent type pollution from happening on Initializer retrieval + *
      + *
    • have a way to log all initializers
      • + *
    • prevent type pollution from happening on Initializer retrieval
      • + *
    * I also consider it good practice to only expose the minimal set of * operations the client actually needs. */ diff --git a/hibernate-core/src/main/java/org/hibernate/sql/results/spi/ListResultsConsumer.java b/hibernate-core/src/main/java/org/hibernate/sql/results/spi/ListResultsConsumer.java index baca843a06..11c0f1fdc7 100644 --- a/hibernate-core/src/main/java/org/hibernate/sql/results/spi/ListResultsConsumer.java +++ b/hibernate-core/src/main/java/org/hibernate/sql/results/spi/ListResultsConsumer.java @@ -33,8 +33,8 @@ import org.checkerframework.checker.nullness.qual.Nullable; public class ListResultsConsumer implements ResultsConsumer, R> { /** - * Let's be reasonable, a row estimate greater than 1M rows is probably either a mis-estimation or bug, - * so let's set 2^20 which is a bit above 1M as maximum collection size. + * Let's be reasonable: a row estimate greater than 1M rows is probably either a misestimate or a bug, + * so let's set {@code 2^20} which is a bit above 1M as maximum collection size. */ private static final int INITIAL_COLLECTION_SIZE_LIMIT = 1 << 20; diff --git a/hibernate-core/src/main/java/org/hibernate/sql/results/spi/RowReader.java b/hibernate-core/src/main/java/org/hibernate/sql/results/spi/RowReader.java index 2f61ea91d1..fbda3398dc 100644 --- a/hibernate-core/src/main/java/org/hibernate/sql/results/spi/RowReader.java +++ b/hibernate-core/src/main/java/org/hibernate/sql/results/spi/RowReader.java @@ -22,9 +22,9 @@ public interface RowReader { * The type actually returned from this reader's {@link #readRow} call, * accounting for any transformers. *

    - * May be null to indicate that no transformation is applied. + * May be {@code null} to indicate that no transformation is applied. *

    - * Ultimately intended for use in comparing values are being de-duplicated + * Ultimately intended for use in comparing values that are being de-duplicated */ Class getDomainResultResultJavaType();