more minor doc fixes

hibernate-core/src/main/java/org/hibernate/boot/model/relational/ColumnOrderingStrategy.java

@@ -20,11 +20,6 @@ import org.hibernate.mapping.UserDefinedType;
  * A pluggable contract that allows ordering of columns within {@link org.hibernate.mapping.Table},
  * {@link org.hibernate.mapping.Constraint} and {@link org.hibernate.mapping.UserDefinedType}.
  * <p>
- * Whenever reasonable, the use of a custom {@linkplain ColumnOrderingStrategy} is highly
- * recommended in preference to tedious and repetitive explicit table and column name
- * mappings. It's anticipated that most projects using Hibernate will feature a custom
- * implementation of {@code ImplicitNamingStrategy}.
- * <p>
  * An {@linkplain ColumnOrderingStrategy} may be selected using the configuration property
  * {@value org.hibernate.cfg.AvailableSettings#COLUMN_ORDERING_STRATEGY}.
  */

hibernate-core/src/main/java/org/hibernate/boot/model/relational/SimpleAuxiliaryDatabaseObject.java

@@ -12,12 +12,12 @@ import org.hibernate.boot.model.naming.Identifier;
 import org.hibernate.internal.util.StringHelper;
 
 /**
- * A simple implementation of AbstractAuxiliaryDatabaseObject in which the CREATE and DROP strings are
- * provided up front.  Contains simple facilities for templating the catalog and schema
- * names into the provided strings.
+ * A simple implementation of {@link AbstractAuxiliaryDatabaseObject} in which the
+ * {@code CREATE} and {@code DROP} strings are provided up front. Contains simple
+ * facilities for templating the catalog and schema names into the provided strings.
  * <p>
- * This is the form created when the mapping documents use &lt;create/&gt; and
- * &lt;drop/&gt;.
+ * This is the form created when the mapping documents use {@code <create/>} and
+ * {@code <drop/>}.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/engine/jdbc/batch/spi/Batch.java

@@ -7,6 +7,7 @@
 package org.hibernate.engine.jdbc.batch.spi;
 
 import java.sql.PreparedStatement;
+import java.util.function.Supplier;
 
 import org.hibernate.Incubating;
 import org.hibernate.engine.jdbc.mutation.JdbcValueBindings;
@@ -14,13 +15,17 @@ import org.hibernate.engine.jdbc.mutation.TableInclusionChecker;
 import org.hibernate.engine.jdbc.mutation.group.PreparedStatementGroup;
 
 /**
- * Conceptually models a batch.
+ * Represents a batch of statements to be executed together.
  * <p>
- * Unlike in JDBC, here we add the ability to batch together multiple statements at a time.  In the underlying
- * JDBC this correlates to multiple {@link PreparedStatement} objects (one for each DML string) maintained within the
- * batch.
+ * Unlike in JDBC, here we add the ability to batch together multiple statements at a time.
+ * In the underlying JDBC this correlates to multiple {@link PreparedStatement} objects,
+ * one for each DML string, all maintained within the batch.
+ * <p>
+ * A batch is usually associated with a {@link org.hibernate.engine.jdbc.spi.JdbcCoordinator}.
  *
  * @author Steve Ebersole
+ * 
+ * @see org.hibernate.engine.jdbc.spi.JdbcCoordinator#getBatch(BatchKey, Integer, Supplier)
  */
 @Incubating
 public interface Batch {
@@ -41,9 +46,8 @@ public interface Batch {
 	PreparedStatementGroup getStatementGroup();
 
 	/**
-	 * Apply the value bindings to the batch JDBC statements
-	 * and
-	 * Indicates completion of the current part of the batch.
+	 * Apply the value bindings to the batch JDBC statements and indicates completion
+	 * of the current part of the batch.
 	 */
 	void addToBatch(JdbcValueBindings jdbcValueBindings, TableInclusionChecker inclusionChecker);
 
@@ -53,8 +57,8 @@ public interface Batch {
 	void execute();
 
 	/**
-	 * Used to indicate that the batch instance is no longer needed and that, therefore, it can release its
-	 * resources.
+	 * Used to indicate that the batch instance is no longer needed and that, therefore,
+	 * it can release its resources.
 	 */
 	void release();
 }

hibernate-core/src/main/java/org/hibernate/engine/jdbc/batch/spi/BatchKey.java

@@ -17,7 +17,7 @@ public interface BatchKey {
 	/**
 	 * How many statements will be in this batch?
 	 * <p>
-	 * Note that this is distinctly different than the size of the batch.
+	 * Note that this is distinctly different to the size of the batch.
 	 *
 	 * @return The number of statements.
 	 *

hibernate-core/src/main/java/org/hibernate/engine/jdbc/internal/StatementPreparerImpl.java

@@ -22,7 +22,7 @@ import org.hibernate.resource.jdbc.spi.JdbcObserver;
 import org.hibernate.resource.jdbc.spi.LogicalConnectionImplementor;
 
 /**
- * Standard implementation of StatementPreparer
+ * Standard implementation of {@link StatementPreparer}.
  *
  * @author Steve Ebersole
  * @author Lukasz Antoniak (lukasz dot antoniak at gmail dot com)

hibernate-core/src/main/java/org/hibernate/engine/jdbc/mutation/group/PreparedStatementGroup.java

@@ -12,7 +12,7 @@ import java.util.function.Predicate;
 import org.hibernate.Incubating;
 
 /**
- * Grouping of {@link java.sql.PreparedStatement} references
+ * Grouping of {@link java.sql.PreparedStatement} references.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/engine/jdbc/spi/JdbcCoordinator.java

@@ -10,6 +10,7 @@ import java.io.IOException;
 import java.io.ObjectOutputStream;
 import java.io.Serializable;
 import java.sql.Connection;
+import java.sql.ResultSet;
 import java.sql.Statement;
 import java.util.function.Supplier;
 
@@ -72,7 +73,7 @@ public interface JdbcCoordinator extends Serializable, TransactionCoordinatorOwn
 	StatementPreparer getStatementPreparer();
 
 	/**
-	 * Obtain the resultset extractor associated with this JDBC coordinator.
+	 * Obtain the {@link ResultSet} extractor associated with this JDBC coordinator.
 	 *
 	 * @return This coordinator's resultset extractor
 	 */

hibernate-core/src/main/java/org/hibernate/engine/jdbc/spi/MutationStatementPreparer.java

@@ -9,9 +9,12 @@ package org.hibernate.engine.jdbc.spi;
 import java.sql.PreparedStatement;
 
 /**
- * Contracting for creating {@link PreparedStatement} instances related to mutations
+ * Interface to the object that prepares JDBC {@link PreparedStatement}s related to mutations
+ * on behalf of a {@link JdbcCoordinator}.
  *
  * @author Steve Ebersole
+ *
+ * @see JdbcCoordinator#getMutationStatementPreparer()
  */
 public interface MutationStatementPreparer {
 	/**

hibernate-core/src/main/java/org/hibernate/engine/jdbc/spi/ResultSetReturn.java

@@ -14,10 +14,13 @@ import java.sql.Statement;
 /**
  * Contract for extracting {@link ResultSet}s from {@link Statement}s, executing the statements,
  * managing resources, and logging statement calls.
+ * <p>
  * Generally the methods here for dealing with {@link CallableStatement} are extremely limited
  *
  * @author Brett Meyer
  * @author Steve Ebersole
+ *
+ * @see JdbcCoordinator#getResultSetReturn()
  */
 //TODO: This could eventually utilize the new Return interface. It would be great to have a common API.
 public interface ResultSetReturn {

hibernate-core/src/main/java/org/hibernate/engine/jdbc/spi/StatementPreparer.java

@@ -12,10 +12,13 @@ import java.sql.Statement;
 import org.hibernate.ScrollMode;
 
 /**
- * Contracting for preparing SQL statements
+ * Interface to the object that prepares JDBC {@link Statement}s and {@link PreparedStatement}s
+ * on behalf of a {@link JdbcCoordinator}.
  *
  * @author Steve Ebersole
  * @author Brett Meyer
+ *
+ * @see JdbcCoordinator#getStatementPreparer()
  */
 public interface StatementPreparer {
 	/**

hibernate-core/src/main/java/org/hibernate/internal/SessionFactoryImpl.java

@@ -135,7 +135,7 @@ import static org.hibernate.query.QueryLogging.QUERY_MESSAGE_LOGGER;
 
 /**
  * Concrete implementation of the {@code SessionFactory} interface. Has the following
- * responsibilities
+ * responsibilities:
  * <ul>
  * <li>caches configuration settings (immutably)
  * <li>caches "compiled" mappings ie. {@code EntityPersister}s and
@@ -289,7 +289,7 @@ public class SessionFactoryImpl implements SessionFactoryImplementor {
 				close();
 			}
 			catch (Exception closeException) {
-				LOG.debugf( "Eating error closing SF on failed attempt to start it" );
+				LOG.debugf( "Eating error closing the SessionFactory after a failed attempt to start it" );
 			}
 			throw e;
 		}

hibernate-core/src/main/java/org/hibernate/resource/jdbc/LogicalConnection.java

@@ -9,14 +9,18 @@ package org.hibernate.resource.jdbc;
 import java.sql.Connection;
 
 /**
- * Models the logical notion of a JDBC Connection.  We may release/re-acquire physical JDBC connections under the
- * covers, but this logically represents the overall access to the JDBC Connection.
+ * Represents a continuous logical connection to the database to the database via JDBC.
+ * <p>
+ * Under the covers, a physical JDBC {@link Connection} might be acquired and then released multiple times,
+ * but those details are hidden from clients.
  *
  * @author Steve Ebersole
  */
 public interface LogicalConnection {
 	/**
-	 * Is this (logical) JDBC Connection still open/active.  In other words, has {@link #close} not been called yet?
+	 * Is this (logical) JDBC connection still open/active?
+	 * <p>
+	 * That is, has {@link #close} not yet been called?
 	 *
 	 * @return {@code true} if still open ({@link #close} has not been called yet); {@code false} if not open
 	 * ({@link #close} has been called).
@@ -24,25 +28,27 @@ public interface LogicalConnection {
 	boolean isOpen();
 
 	/**
-	 * Closes the JdbcSession, making it inactive and forcing release of any held resources
+	 * Closes the JdbcSession, making it inactive and forcing release of any held resources.
 	 *
-	 * @return Legacy :(  Returns the JDBC Connection *if* the user passed in a Connection originally.
+	 * @return Legacy :(  Returns the JDBC {@code Connection} if the user passed in a {@code Connection} originally.
 	 */
 	Connection close();
 
 	/**
-	 * Is this JdbcSession currently physically connected (meaning does it currently hold a JDBC Connection)?
+	 * Is this JdbcSession currently physically connected?
+	 * <p>
+	 * That is, does it currently hold a physical JDBC {@code Connection}?
 	 *
-	 * @return {@code true} if the JdbcSession currently hold a JDBC Connection; {@code false} if it does not.
+	 * @return {@code true} if the JdbcSession currently hold a JDBC {@code Connection}; {@code false} if it does not.
 	 */
 	boolean isPhysicallyConnected();
 
 	/**
-	 * Provides access to the registry of JDBC resources associated with this LogicalConnection.
+	 * Provides access to the registry of JDBC resources associated with this {@code LogicalConnection}.
 	 *
 	 * @return The JDBC resource registry.
 	 *
-	 * @throws org.hibernate.ResourceClosedException if the LogicalConnection is closed
+	 * @throws org.hibernate.ResourceClosedException if the {@code LogicalConnection} is closed
 	 */
 	ResourceRegistry getResourceRegistry();
 

hibernate-core/src/main/java/org/hibernate/resource/jdbc/ResourceRegistry.java

@@ -13,7 +13,7 @@ import java.sql.ResultSet;
 import java.sql.Statement;
 
 /**
- * A registry for tracking JDBC resources
+ * A registry for tracking JDBC resources.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/resource/jdbc/package-info.java

@@ -6,7 +6,7 @@
  */
 
 /**
- * A facility for managing JDBC connections and other heavyweight resources.
+ * A facility for managing logical JDBC connections and keeping track of other heavyweight resources.
  *
  * @see org.hibernate.resource.jdbc.LogicalConnection
  * @see org.hibernate.resource.jdbc.ResourceRegistry

hibernate-core/src/main/java/org/hibernate/resource/jdbc/spi/LogicalConnectionImplementor.java

@@ -16,10 +16,12 @@ import org.hibernate.resource.jdbc.LogicalConnection;
  * SPI contract for {@link LogicalConnection}.
  *
  * @author Steve Ebersole
+ *
+ * @see org.hibernate.engine.jdbc.spi.JdbcCoordinator#getLogicalConnection()
  */
 public interface LogicalConnectionImplementor extends LogicalConnection {
 	/**
-	 * Exposes access to the "real" Connection.
+	 * Exposes access to the "real" {@link Connection}.
 	 *
 	 * @todo : expose Connection as here?  or accept(WorkInConnection) where WorkInConnection is given access to Connection?
 	 *
@@ -30,48 +32,55 @@ public interface LogicalConnectionImplementor extends LogicalConnection {
 	PhysicalConnectionHandlingMode getConnectionHandlingMode();
 
 	/**
-	 * Notification indicating a JDBC statement has been executed to trigger
-	 * {@link org.hibernate.ConnectionReleaseMode#AFTER_STATEMENT} releasing if needed
+	 * Notification indicating a JDBC statement has been executed, to trigger
+	 * {@link org.hibernate.ConnectionReleaseMode#AFTER_STATEMENT} releasing
+	 * if needed.
 	 */
 	void afterStatement();
 
 	/**
-	 * Notification indicating a transaction is about to be completed, so to trigger
-	 * releasing of the connection if needed ({@link org.hibernate.ConnectionReleaseMode#BEFORE_TRANSACTION_COMPLETION}
-	 * is enabled)
+	 * Notification indicating a transaction is about to be completed, to
+	 * trigger release of the JDBC connection if needed, that is, if
+	 * {@link org.hibernate.ConnectionReleaseMode#BEFORE_TRANSACTION_COMPLETION}
+	 * is enabled.
 	 */
 	void beforeTransactionCompletion();
 
 	/**
-	 * Notification indicating a transaction has completed to trigger
-	 * {@link org.hibernate.ConnectionReleaseMode#AFTER_TRANSACTION} releasing if needed
+	 * Notification indicating a transaction has just completed, to trigger
+	 * {@link org.hibernate.ConnectionReleaseMode#AFTER_TRANSACTION} releasing
+	 * if needed.
 	 */
 	void afterTransaction();
 
 	/**
-	 * Manually disconnect the underlying JDBC Connection.  The assumption here
-	 * is that the manager will be reconnected at a later point in time.
+	 * Manually disconnect the underlying JDBC Connection.
+	 * The assumption here is that the manager will be reconnected at a
+	 * later point in time.
 	 *
-	 * @return The connection maintained here at time of disconnect.  {@code null} if
-	 * there was no connection cached internally.
+	 * @return The connection maintained here at time of disconnect.
+	 *         {@code null} if there was no connection cached internally.
 	 */
 	Connection manualDisconnect();
 
 	/**
-	 * Manually reconnect the underlying JDBC Connection.  Should be called at some point after manualDisconnect().
+	 * Manually reconnect the underlying JDBC Connection.
+	 * Should be called at some point after {@link #manualDisconnect()}.
 	 *
-	 * @param suppliedConnection For user supplied connection strategy the user needs to hand us the connection
-	 * with which to reconnect.  It is an error to pass a connection in the other strategies.
+	 * @param suppliedConnection For user supplied connection strategy the
+	 *                           user needs to hand us the connection with
+	 *                           which to reconnect. It is an error to pass
+	 *                           a connection in the other strategies.
 	 */
 	void manualReconnect(Connection suppliedConnection);
 
 	/**
-	 * Access to the current underlying JDBC transaction
+	 * Access to the current underlying JDBC transaction.
 	 */
 	PhysicalJdbcTransaction getPhysicalJdbcTransaction();
 
 	/**
-	 * Serialization hook
+	 * Serialization hook.
 	 *
 	 * @param oos The stream to write out state to
 	 *