improve jdoc for some JdbcSettings and deprecate one of them

Author: gavinking

hibernate-core/src/main/java/org/hibernate/cfg/Environment.java

@@ -50,7 +50,7 @@
  * <tr>
  *   <td>{@value #CONNECTION_PROVIDER}</td>
  *   <td>name of a {@link org.hibernate.engine.jdbc.connections.spi.ConnectionProvider}
- *   subclass (if not specified heuristics are used)</td>
+ *   subclass (if not specified, heuristics are used)</td>
  * </tr>
  * <tr><td>{@value #USER}</td><td>database username</td></tr>
  * <tr><td>{@value #PASS}</td><td>database password</td></tr>

hibernate-core/src/main/java/org/hibernate/cfg/JdbcSettings.java

@@ -225,17 +225,17 @@ public interface JdbcSettings extends C3p0Settings, AgroalSettings, HikariCPSett
 	String DIALECT_RESOLVERS = "hibernate.dialect_resolvers";
 
 	/**
-	 * Specifies a {@link ConnectionProvider}
-	 * to use for obtaining JDBC connections, either:
+	 * Specifies a {@link ConnectionProvider} to use for obtaining JDBC connections,
+	 * either:
 	 * <ul>
 	 *     <li>an instance of {@code ConnectionProvider},
 	 *     <li>a {@link Class} representing a class that implements
 	 *         {@code ConnectionProvider}, or
 	 *     <li>the name of a class that implements {@code ConnectionProvider}.
 	 * </ul>
-	 * <p>
-	 * The term {@code "class"} appears in the setting name due to legacy reasons;
-	 * however it can accept instances.
+	 *
+	 * @apiNote The term {@code "class"} appears in the setting name due to legacy reasons;
+	 *          however it can accept instances.
 	 */
 	String CONNECTION_PROVIDER = "hibernate.connection.provider_class";
 
@@ -249,31 +249,41 @@ public interface JdbcSettings extends C3p0Settings, AgroalSettings, HikariCPSett
 	String POOL_SIZE = "hibernate.connection.pool_size";
 
 	/**
-	 * Specified the JDBC transaction isolation level.
+	 * Specifies the JDBC transaction isolation level for connections obtained
+	 * from any {@link ConnectionProvider} implementation which respects this
+	 * setting, including every built-in implementation except for
+	 * {@link org.hibernate.engine.jdbc.connections.internal.DatasourceConnectionProviderImpl}.
+	 * <p>
+	 * Possible values are enumerated by {@link java.sql.Connection}:
+	 * {@code NONE}, {@code READ_UNCOMMITTED}, {@code READ_COMMITTED},
+	 * {@code REPEATABLE_READ}, {@code SERIALIZABLE}.
+	 * <p>
+	 * If this setting is not explicitly specified, Hibernate does not modify
+	 * the transaction isolation level of the JDBC connection.
 	 */
 	String ISOLATION = "hibernate.connection.isolation";
 
 	/**
 	 * Controls the autocommit mode of JDBC connections obtained from any
 	 * {@link ConnectionProvider} implementation which respects this setting,
-	 * which includes the built-in implementations do, except for
+	 * including every built-in implementation except for
 	 * {@link org.hibernate.engine.jdbc.connections.internal.DatasourceConnectionProviderImpl}.
 	 *
 	 * @settingDefault {@code false}
 	 */
 	String AUTOCOMMIT = "hibernate.connection.autocommit";
 
 	/**
-	 * Indicates that Connections obtained from the configured {@link ConnectionProvider} have
+	 * Indicates that connections obtained from the configured {@link ConnectionProvider} have
 	 * auto-commit already disabled when they are acquired.
 	 * <p>
-	 * It is inappropriate to set this value to {@code true} when the Connections returned by
-	 * the provider do not, in fact, have auto-commit disabled.  Doing so may lead to Hibernate
+	 * It is inappropriate to set this value to {@code true} when the connections returned by
+	 * the provider do not, in fact, have auto-commit disabled. Doing so may lead to Hibernate
 	 * executing SQL operations outside the scope of any transaction.
 	 *
-	 * @apiNote By default, Hibernate calls {@link java.sql.Connection#setAutoCommit(boolean)} on
-	 * newly-obtained connections.  This setting allows to circumvent that call (as well as other
-	 * operations) in the interest of performance.
+	 * @apiNote By default, Hibernate calls {@link java.sql.Connection#setAutoCommit(boolean)}
+	 * on newly-obtained connections. With this setting enabled, that call is skipped, along
+	 * with some other operations, in the interest of performance.
 	 *
 	 * @settingDefault {@code false}
 	 *
@@ -289,7 +299,11 @@ public interface JdbcSettings extends C3p0Settings, AgroalSettings, HikariCPSett
 	 * <p>
 	 * For example, declaring {@code hibernate.connection.foo=bar} tells Hibernate to
 	 * append {@code foo=bar} to the JDBC connection URL.
+	 *
+	 * @deprecated This setting is only supported by {@code C3P0ConnectionProvider}
+	 * and {@link org.hibernate.engine.jdbc.connections.internal.DriverManagerConnectionProviderImpl}.
 	 */
+	@Deprecated(since="7")
 	String CONNECTION_PREFIX = "hibernate.connection";
 
 	/**

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

@@ -178,7 +178,6 @@ else if ( connectionCreatorFactory != null ) {
 		);
 
 		return factory.create(
-
 				driver,
 				serviceRegistry,
 				url,