improve some Javadocs in sql package (#9228)

* improve some Javadocs in sql package

---------

Co-authored-by: nathan.xu <nathan.xu@procor.com>
Co-authored-by: Gavin King <gavin@hibernate.org>

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
  */

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:
  * <ul>
- *     <li>any backtick-quoted identifiers, for example {@code `hello`},
+ *     <li>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</li>
  *     <li>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}.
  *     </li>

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
+	 * Used as indicator of processing predicates (where clause)
-	 * of processing predicates (where clause) that occur in a
+	 * that occur in a delete
-	 * delete
 	 */
 	DELETE,
 	MERGE,
@@ -64,9 +63,6 @@ public enum Clause {
 	CONFLICT,
 	CALL,
 
-	/**
-	 * Again, not used in 5.x.  Used in 6+
-	 */
 	IRRELEVANT
 
 }

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 " ),
 

hibernate-core/src/main/java/org/hibernate/sql/ast/SqlAstTranslator.java

@@ -57,8 +57,8 @@ public interface SqlAstTranslator<T extends JdbcOperation> extends SqlAstWalker
 	Stack<Clause> getCurrentClauseStack();
 
 	/**
-	 * Not the best spot for this.  Its the table names collected while walking the SQL AST.
+	 * Not the best spot for this.  Returns 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
+	 * 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.

hibernate-core/src/main/java/org/hibernate/sql/ast/spi/AbstractSqlAstTranslator.java

@@ -246,7 +246,7 @@ public abstract class AbstractSqlAstTranslator<T extends JdbcOperation> 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.
 	 */

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
  */

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,
 	/**

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

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<NavigablePath, Initializer>}
- * 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
+ * <ul>
- * b) prevent type pollution from happening on Initializer retrieval
+ *     <li>have a way to log all initializers</li>
+ *     <li>prevent type pollution from happening on Initializer retrieval</li>
+ * </ul>
  * I also consider it good practice to only expose the minimal set of
  * operations the client actually needs.
  */

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<R> implements ResultsConsumer<List<R>, R> {
 
 	/**
-	 * Let's be reasonable, a row estimate greater than 1M rows is probably either a mis-estimation or bug,
+	 * Let's be reasonable: a row estimate greater than 1M rows is probably either a misestimate or a bug,
-	 * so let's set 2^20 which is a bit above 1M as maximum collection size.
+	 * 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;
 

hibernate-core/src/main/java/org/hibernate/sql/results/spi/RowReader.java

@@ -22,9 +22,9 @@ public interface RowReader<R> {
 	 * The type actually returned from this reader's {@link #readRow} call,
 	 * accounting for any transformers.
 	 * <p>
-	 * May be null to indicate that no transformation is applied.
+	 * May be {@code null} to indicate that no transformation is applied.
 	 * <p>
-	 * Ultimately intended for use in comparing values are being de-duplicated
+	 * Ultimately intended for use in comparing values that are being de-duplicated
 	 */
 	Class<R> getDomainResultResultJavaType();