javadoc some things about falling back from JPA to native APIs

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

@@ -13,6 +13,11 @@ package org.hibernate.jpa;
  * Some hints are only effective in certain scenarios, which is noted 
  * on each constant's documentation.
  *
+ * @apiNote The stringly-typed hints defined here correspond to
+ *          typesafe operations of Hibernate's native APIs, and
+ *          should not be used unless portability between JPA
+ *          implementations is of very great importance.
+ *
  * @author Steve Ebersole
  */
 public interface HibernateHints {

hibernate-core/src/main/javadoc/overview.html

@@ -59,6 +59,16 @@
     For example, <code>SessionFactory</code> extends <code>EntityManagerFactory</code>, and
     <code>Session</code> extends <code>EntityManager</code>.
 </p>
+<p>
+    It's always possible to fall back from JPA interfaces to native APIs, by calling
+    {@link jakarta.persistence.EntityManager#unwrap entityManager.unwrap(Session.class)},
+    {@link jakarta.persistence.EntityManagerFactory#unwrap entityManagerFactory.unwrap(SessionFactory.class)},
+    or {@link jakarta.persistence.Query#unwrap query.unwrap(Query.class)}. In certain cases
+    it's also possible to access native functionality by passing a
+    {@linkplain org.hibernate.jpa.SpecHints JPA-defined} or
+    {@linkplain org.hibernate.jpa.HibernateHints Hibernate-defined} hint, at the cost of a
+    loss of type-safety.
+</p>
 
 <h3>Mapping annotations</h3>
 

release/src/release/javadoc/overview.html

@@ -59,6 +59,17 @@
     For example, <code>SessionFactory</code> extends <code>EntityManagerFactory</code>, and
     <code>Session</code> extends <code>EntityManager</code>.
 </p>
+<p>
+    It's always possible to fall back from JPA interfaces to native APIs, by calling
+    {@link jakarta.persistence.EntityManager#unwrap entityManager.unwrap(Session.class)},
+    {@link jakarta.persistence.EntityManagerFactory#unwrap entityManagerFactory.unwrap(SessionFactory.class)},
+    or {@link jakarta.persistence.Query#unwrap query.unwrap(Query.class)}. In certain cases
+    it's also possible to access native functionality by passing a
+    {@linkplain org.hibernate.jpa.SpecHints JPA-defined} or
+    {@linkplain org.hibernate.jpa.HibernateHints Hibernate-defined} hint, at the cost of a
+    loss of type-safety.
+</p>
+
 
 <h3>Mapping annotations</h3>