second phase of Javadoc refresh for settings

hibernate-core/src/main/java/org/hibernate/SessionFactory.java

@@ -73,7 +73,8 @@ public interface SessionFactory extends EntityManagerFactory, Referenceable, Ser
 	 * for use.
 	 * <p/>
 	 * Note that for backwards compatibility, if a {@link org.hibernate.context.spi.CurrentSessionContext}
-	 * is not configured but JTA is configured this will default to the {@link org.hibernate.context.internal.JTASessionContext}
+	 * is not configured but JTA is configured this will default to the
+	 * {@link org.hibernate.context.internal.JTASessionContext}
 	 * impl.
 	 *
 	 * @return The current session.

hibernate-core/src/main/java/org/hibernate/SessionFactoryObserver.java

@@ -9,7 +9,10 @@ package org.hibernate;
 import java.io.Serializable;
 
 /**
- * Allows reaction to basic {@link SessionFactory} occurrences.
+ * Allows reaction to basic {@link SessionFactory} lifecycle events.
+ * <p>
+ * A {@code SessionFactoryObserver} may be registered using the configuration property
+ * {@value org.hibernate.cfg.AvailableSettings#SESSION_FACTORY_OBSERVER}.
  *
  * @author Steve Ebersole
  */
@@ -24,8 +27,8 @@ public interface SessionFactoryObserver extends Serializable {
 	}
 
 	/**
-	 * Callback to indicate that the given factory is about to close.  The passed factory reference should be usable
+	 * Callback to indicate that the given factory is about to close.  The passed factory
-	 * since it is only about to close.
+	 * reference should be usable since it is only about to close.
 	 * <p/>
 	 * NOTE : defined as default to allow for existing SessionFactoryObserver impls to work
 	 * in 5.2.  Starting in 6.0 the default will be removed and SessionFactoryObserver impls

hibernate-core/src/main/java/org/hibernate/boot/model/naming/PhysicalNamingStrategy.java

@@ -11,6 +11,9 @@ import org.hibernate.engine.jdbc.env.spi.JdbcEnvironment;
 
 /**
  * Pluggable strategy contract for applying physical naming rules for database object names.
+ * <p>
+ * A {@code PhysicalNamingStrategy} may be selected using the configuration property
+ * {@value org.hibernate.cfg.AvailableSettings#PHYSICAL_NAMING_STRATEGY}.
  *
  * @author Steve Ebersole
  */

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

@@ -10,7 +10,10 @@ import org.hibernate.engine.jdbc.spi.JdbcCoordinator;
 import org.hibernate.service.Service;
 
 /**
- * A builder for {@link Batch} instances
+ * A builder for {@link Batch} instances.
+ * <p>
+ * A custom {@code BatchBuilder} may be selected using the configuration property
+ * {@value org.hibernate.cfg.AvailableSettings#BATCH_STRATEGY}.
  *
  * @author Steve Ebersole
  */

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

@@ -22,7 +22,7 @@ import org.hibernate.service.spi.ServiceException;
 import org.hibernate.service.spi.ServiceRegistryImplementor;
 
 /**
- * Template (as in template pattern) support for ConnectionCreator implementors.
+ * Template (as in template pattern) support for {@linl ConnectionCreator} implementors.
  *
  * @author Steve Ebersole
  */

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

@@ -9,7 +9,7 @@ package org.hibernate.engine.jdbc.connections.internal;
 import java.sql.Connection;
 
 /**
- * Contract for creating JDBC Connections on demand
+ * Contract for creating JDBC {@linkplain Connection connections} on demand.
  *
  * @author Steve Ebersole
  */

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

@@ -13,7 +13,7 @@ import java.util.Properties;
 import org.hibernate.service.spi.ServiceRegistryImplementor;
 
 /**
- * The default factory for ConnectionCreator instances
+ * The default factory for {@link ConnectionCreator} instances.
  *
  * @author Christian Beikov
  */

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

@@ -10,7 +10,7 @@ import java.sql.Connection;
 import java.sql.SQLException;
 
 /**
- * Contract for validating JDBC Connections
+ * Contract for validating JDBC {@linkplain Connection connections}.
  *
  * @author Christian Beikov
  */

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

@@ -24,9 +24,9 @@ import org.hibernate.service.spi.Stoppable;
  * A {@link ConnectionProvider} that manages connections from an underlying {@link DataSource}.
  * <p/>
  * The {@link DataSource} to use may be specified by either:<ul>
- * <li>injection using {@link #setDataSource}</li>
+ * <li>injection using {@link #setDataSource}
- * <li>declaring the {@link DataSource} instance using the {@value Environment#DATASOURCE} config property</li>
+ * <li>declaring the {@link DataSource} instance using the {@value Environment#DATASOURCE} config property
- * <li>declaring the JNDI name under which the {@link DataSource} can be found via the {@value Environment#DATASOURCE} config property</li>
+ * <li>declaring the JNDI name under which the {@link DataSource} is found via the {@value Environment#DATASOURCE} config property
  * </ul>
  *
  * @author Gavin King

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

@@ -14,7 +14,8 @@ import java.util.Properties;
 import org.hibernate.service.spi.ServiceRegistryImplementor;
 
 /**
- * A specialized ConnectionCreator which uses {@link Driver#connect} to generate Connections
+ * A specialized {@link ConnectionCreator} which uses {@link Driver#connect(String, Properties)}
+ * to obtain JDBC connections.
  *
  * @author Steve Ebersole
  */

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

@@ -14,7 +14,8 @@ import java.util.Properties;
 import org.hibernate.service.spi.ServiceRegistryImplementor;
 
 /**
- * A specialized ConnectionCreator which uses {@link DriverManager#getConnection} to generate Connections
+ * A specialized {@link ConnectionCreator} which uses {@link DriverManager#getConnection(String, Properties)}
+ * to obtain JDBC connections.
  *
  * @author Steve Ebersole
  */

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

@@ -43,9 +43,6 @@ import static org.hibernate.internal.log.ConnectionPoolingLogger.CONNECTIONS_MES
  * a very rudimentary connection pool.
  * <p/>
  * IMPL NOTE : not intended for production use!
- * <p/>
- * Thanks to Oleg Varaksin and his article on object pooling using the {@link java.util.concurrent} package, from
- * which much of the pooling code here is derived.  See http://ovaraksin.blogspot.com/2013/08/simple-and-lightweight-pool.html
  *
  * @author Gavin King
  * @author Steve Ebersole
@@ -53,6 +50,10 @@ import static org.hibernate.internal.log.ConnectionPoolingLogger.CONNECTIONS_MES
 public class DriverManagerConnectionProviderImpl
 		implements ConnectionProvider, Configurable, Stoppable, ServiceRegistryAwareService, ConnectionValidator {
 
+	//Thanks to Oleg Varaksin and his article on object pooling using the {@link java.util.concurrent}
+	//package, from which much of the pooling code here is derived.
+	//See http://ovaraksin.blogspot.com/2013/08/simple-and-lightweight-pool.html
+
 	public static final String MIN_SIZE = "hibernate.connection.min_pool_size";
 	public static final String INITIAL_SIZE = "hibernate.connection.initial_pool_size";
 	// in TimeUnit.SECONDS

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

@@ -20,7 +20,7 @@ import org.hibernate.service.spi.ServiceRegistryImplementor;
 import org.jboss.logging.Logger;
 
 /**
- * A service initiator for the MultiTenantConnectionProvider service
+ * A service initiator for the {@link MultiTenantConnectionProvider} service.
  *
  * @author Steve Ebersole
  */

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

@@ -13,9 +13,9 @@ import org.hibernate.engine.jdbc.connections.spi.ConnectionProvider;
 import org.hibernate.service.UnknownUnwrapTypeException;
 
 /**
- * An implementation of the {@link ConnectionProvider} interface that simply throws an exception when a connection
+ * An implementation of the {@link ConnectionProvider} interface that simply throws an
- * is requested, the assumption being that the application is responsible for handing the connection to use to
+ * exception when a connection is requested, the assumption being that the application
- * the session
+ * is responsible for handing the connection to use to the session.
  *
  * @author Gavin King
  * @author Steve Ebersole

hibernate-core/src/main/java/org/hibernate/id/factory/spi/GenerationTypeStrategyRegistration.java

@@ -12,7 +12,8 @@ import jakarta.persistence.GenerationType;
 import org.hibernate.service.ServiceRegistry;
 
 /**
- * {@link java.util.ServiceLoader} contract for registering GenerationTypeStrategy impls
+ * A {@link java.util.ServiceLoader} contract for registering implementations
+ * of {@link GenerationTypeStrategy}.
  */
 public interface GenerationTypeStrategyRegistration {
 	void registerStrategies(BiConsumer<GenerationType, GenerationTypeStrategy> registry, ServiceRegistry serviceRegistry);

hibernate-core/src/main/java/org/hibernate/jpa/spi/IdentifierGeneratorStrategyProvider.java

@@ -9,7 +9,8 @@ package org.hibernate.jpa.spi;
 import java.util.Map;
 
 /**
- * Provide a set of IdentifierGenerator strategies allowing to override the Hibernate Core default ones
+ * Provides a set of {@link org.hibernate.id.IdentifierGenerator} strategies,
+ * overriding the default strategies.
  *
  * @author <a href="mailto:emmanuel@hibernate.org">Emmanuel Bernard</a>
  *

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

@@ -19,7 +19,10 @@ import static org.hibernate.ConnectionReleaseMode.BEFORE_TRANSACTION_COMPLETION;
 import static org.hibernate.ConnectionReleaseMode.ON_CLOSE;
 
 /**
- * Represents valid combinations of ConnectionAcquisitionMode and ConnectionReleaseMode
+ * Enumerates valid combinations of {@link ConnectionAcquisitionMode} and
+ * {@link ConnectionReleaseMode}.
+ *
+ * @see org.hibernate.cfg.AvailableSettings#CONNECTION_HANDLING
  *
  * @author Steve Ebersole
  */
@@ -36,18 +39,18 @@ public enum PhysicalConnectionHandlingMode {
 	 */
 	DELAYED_ACQUISITION_AND_HOLD( AS_NEEDED, ON_CLOSE ),
 	/**
-	 * The Connection will be acquired as soon as it is needed; it will be released
+	 * The Connection will be acquired as soon as it is needed; it will be
-	 * after each statement is executed.
+	 * released after each statement is executed.
 	 */
 	DELAYED_ACQUISITION_AND_RELEASE_AFTER_STATEMENT( AS_NEEDED, AFTER_STATEMENT ),
 	/**
-	 * The Connection will be acquired as soon as it is needed; it will be released
+	 * The Connection will be acquired as soon as it is needed; it will be
-	 * before commit/rollback.
+	 * released before commit/rollback.
 	 */
 	DELAYED_ACQUISITION_AND_RELEASE_BEFORE_TRANSACTION_COMPLETION( AS_NEEDED, BEFORE_TRANSACTION_COMPLETION ),
 	/**
-	 * The Connection will be acquired as soon as it is needed; it will be released
+	 * The Connection will be acquired as soon as it is needed; it will be
-	 * after each transaction is completed.
+	 * released after each transaction is completed.
 	 */
 	DELAYED_ACQUISITION_AND_RELEASE_AFTER_TRANSACTION( AS_NEEDED, AFTER_TRANSACTION )
 	;