From 08569e2fa29f485d2e557813ae485b114232affe Mon Sep 17 00:00:00 2001
From: Gavin King <gavin@hibernate.org>
Date: Sun, 24 Nov 2024 10:08:24 +0100
Subject: [PATCH] add an API note to HibernatePersistenceConfiguration

---
 .../hibernate/jpa/HibernatePersistenceConfiguration.java | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/hibernate-core/src/main/java/org/hibernate/jpa/HibernatePersistenceConfiguration.java b/hibernate-core/src/main/java/org/hibernate/jpa/HibernatePersistenceConfiguration.java
index 33926aca3b63..682fe2a71e4c 100644
--- a/hibernate-core/src/main/java/org/hibernate/jpa/HibernatePersistenceConfiguration.java
+++ b/hibernate-core/src/main/java/org/hibernate/jpa/HibernatePersistenceConfiguration.java
@@ -32,6 +32,12 @@
  * Hibernate extension to the Jakarta Persistence {@link PersistenceConfiguration}
  * contract.
  *
+ * @apiNote The specification explicitly encourages implementors to extend
+ *          {@link PersistenceConfiguration} to accommodate vendor-specific
+ *          extensions in a more typesafe way. Of course, programs which
+ *          desire configuration logic to be portable between JPA providers
+ *          should use {@code PersistenceConfiguration} directly.
+ *
  * @author Steve Ebersole
  *
  * @since 7.0
@@ -49,6 +55,9 @@ public HibernatePersistenceConfiguration(String name) {
 		super( name );
 	}
 
+	/**
+	 * Create a new {@link SessionFactory} based on this configuration.
+	 */
 	@Override
 	public SessionFactory createEntityManagerFactory() {
 		return (SessionFactory) super.createEntityManagerFactory();