Javadoc for Configuration properties

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

@@ -74,15 +74,28 @@
  * <li>{@linkplain #setProperty(String, String) configuration properties}
  *     from various sources, and
  * <li>entity O/R mappings, defined in either {@linkplain #addAnnotatedClass
- *    annotated classes}, or {@linkplain #addFile XML mapping documents}.
+ *     annotated classes}, or {@linkplain #addFile XML mapping documents}.
  * </ul>
  * <p>
  * Note that XML mappings may be expressed using the JPA {@code orm.xml}
  * format, or in Hibernate's legacy {@code .hbm.xml} format.
  * <p>
  * Configuration properties are enumerated by {@link AvailableSettings}.
+ * <p>
+ * When instantiated, an instance of {@code Configuration} has its properties
+ * initially populated from the {@linkplain Environment#getProperties()
+ * environment}, including:
+ * <ul>
+ * <li>JVM {@linkplain System#getProperties() system properties}, and
+ * <li>properties specified in {@code hibernate.properties}.
+ * </ul>
+ * <p>
+ * These initial properties may be completely discarded by calling
+ * {@link #setProperties(Properties)}, or they may be overridden
+ * individually by calling {@link #setProperty(String, String)}.
+ * <p>
  * <pre>
- *  SessionFactory factory = new Configuration()
+ * SessionFactory factory = new Configuration()
  *     // scan classes for mapping annotations
  *     .addAnnotatedClass(Item.class)
  *     .addAnnotatedClass(Bid.class)

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

@@ -163,7 +163,7 @@ public final class Environment implements AvailableSettings {
 		}
 
 		try {
-			Properties systemProperties = System.getProperties();
+			final Properties systemProperties = System.getProperties();
 			// Must be thread-safe in case an application changes System properties during Hibernate initialization.
 			// See HHH-8383.
 			synchronized (systemProperties) {
@@ -183,11 +183,11 @@ private Environment() {
 	}
 
 	/**
-	 * The {@link System#getProperties() system properties}, extended with all
-	 * additional properties specified in {@code hibernate.properties}.
+	 * The {@linkplain System#getProperties() system properties}, extended
+	 * with all additional properties specified in {@code hibernate.properties}.
 	 */
 	public static Properties getProperties() {
-		Properties copy = new Properties();
+		final Properties copy = new Properties();
 		copy.putAll(GLOBAL_PROPERTIES);
 		return copy;
 	}

hibernate-core/src/main/java/org/hibernate/jpa/HibernatePersistenceConfiguration.java

@@ -13,6 +13,7 @@
 import org.hibernate.cache.spi.access.AccessType;
 import org.hibernate.cfg.AvailableSettings;
 import org.hibernate.cfg.CacheSettings;
+import org.hibernate.cfg.Environment;
 import org.hibernate.cfg.JdbcSettings;
 import org.hibernate.cfg.JpaComplianceSettings;
 import org.hibernate.cfg.MappingSettings;
@@ -29,8 +30,42 @@
 import jakarta.persistence.ValidationMode;
 
 /**
- * Hibernate extension to the Jakarta Persistence {@link PersistenceConfiguration}
- * contract.
+ * Extends the Jakarta Persistence-defined {@link PersistenceConfiguration}
+ * with operations specific to Hibernate.
+ * <p>
+ * An instance of {@code Configuration} may be obtained simply by
+ * {@linkplain #HibernatePersistenceConfiguration(String) instantiation},
+ * and may be used to aggregate:
+ * <ul>
+ * <li>{@linkplain #property(String, Object) configuration properties}
+ *     from various sources, and
+ * <li>entity O/R mappings, defined in either
+ *     {@linkplain #managedClasses(Class...) annotated classes}, or
+ *     {@linkplain #mappingFiles(Collection) XML mapping documents}.
+ * </ul>
+ * <p>
+ * Standard JPA configuration properties are enumerated by the supertype
+ * {@link PersistenceConfiguration}. All configuration properties understood
+ * by Hibernate are enumerated by {@link AvailableSettings}.
+ * <p>
+ * <pre>
+ * SessionFactory factory = new HibernatePersistenceConfiguration()
+ *     // scan classes for mapping annotations
+ *     .managedClasses(Item.class, Bid.class, User.class)
+ *     // set a configuration property
+ *     .setProperty(PersistenceConfiguration.JDBC_DATASOURCE,
+ *                  "java:comp/env/jdbc/test")
+ *     .buildSessionFactory();
+ * </pre>
+ * <p>
+ * When instantiated, an instance of
+ * {@code HibernatePersistenceConfiguration} has its properties initially
+ * populated from the {@linkplain Environment#getProperties() environment},
+ * including:
+ * <ul>
+ * <li>JVM {@linkplain System#getProperties() system properties}, and
+ * <li>properties specified in {@code hibernate.properties}.
+ * </ul>
  *
  * @apiNote The specification explicitly encourages implementors to extend
  *          {@link PersistenceConfiguration} to accommodate vendor-specific