From 7f5e80145d8b9160f4f4d38dac34a1e4b0f214fb Mon Sep 17 00:00:00 2001
From: Gavin King <gavin@hibernate.org>
Date: Fri, 21 Jul 2023 20:51:18 +0200
Subject: [PATCH] add some links to Javadoc overview

---
 hibernate-core/src/main/javadoc/overview.html | 34 +++++++++++++++++--
 release/src/release/javadoc/overview.html     | 34 +++++++++++++++++--
 2 files changed, 64 insertions(+), 4 deletions(-)

diff --git a/hibernate-core/src/main/javadoc/overview.html b/hibernate-core/src/main/javadoc/overview.html
index 8415146b4c..fa692b4901 100644
--- a/hibernate-core/src/main/javadoc/overview.html
+++ b/hibernate-core/src/main/javadoc/overview.html
@@ -19,11 +19,14 @@
     <li>
         an implementation of the <em>Java (or Jakarta) Persistence API</em> (JPA),
         where the equivalent central interfaces are {@link jakarta.persistence.EntityManagerFactory}
-        and {@link jakarta.persistence.EntityManager}, and
+        and {@link jakarta.persistence.EntityManager},
     </li>
     <li>
         a set of <em>mapping annotations</em> which augment the O/R mapping annotations defined
-        by JPA, and which may be used with either API.
+        by JPA, and which may be used with either API, and
+    </li>
+    <li>
+        <em>compile-time tooling</em> for writing more type-safe code.
     </li>
 </ul>
 
@@ -59,6 +62,23 @@
     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>
+<p>
+    These packages define additional extensions to the JPA APIs:
+</p>
+<ul>
+    <li>{@link org.hibernate.query.criteria} packages extensions to {@link jakarta.persistence.criteria}, and</li>
+    <li>{@link org.hibernate.metamodel.model.domain} packages extensions to {@link jakarta.persistence.metamodel}.</li>
+</ul>
 
 <h3>Mapping annotations</h3>
 
@@ -96,6 +116,16 @@ mappings as an alternative.
     </li>
 </ul>
 
+<h3>Annotations driving compile-time tooling</h3>
+
+<p>
+    The annotations defined by {@link org.hibernate.annotations.processing} instruct the Metamodel
+    Generator to {@linkplain org.hibernate.annotations.processing.CheckHQL validate HQL at compile
+    time}, and to automatically generate the implementation of
+    {@linkplain org.hibernate.annotations.processing.Find finder methods} and
+    {@linkplain org.hibernate.annotations.processing.HQL query methods}.
+<p>
+
 <h3>Bootstrapping Hibernate</h3>
 
 <p>
diff --git a/release/src/release/javadoc/overview.html b/release/src/release/javadoc/overview.html
index eb6ed96692..0cdf87796e 100644
--- a/release/src/release/javadoc/overview.html
+++ b/release/src/release/javadoc/overview.html
@@ -19,11 +19,14 @@
     <li>
         an implementation of the <em>Java (or Jakarta) Persistence API</em> (JPA),
         where the equivalent central interfaces are {@link jakarta.persistence.EntityManagerFactory}
-        and {@link jakarta.persistence.EntityManager}, and
+        and {@link jakarta.persistence.EntityManager},
     </li>
     <li>
         a set of <em>mapping annotations</em> which augment the O/R mapping annotations defined
-        by JPA, and which may be used with either API.
+        by JPA, and which may be used with either API, and
+    </li>
+    <li>
+        <em>compile-time tooling</em> for writing more type-safe code.
     </li>
 </ul>
 
@@ -59,6 +62,23 @@
     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>
+<p>
+    These packages define additional extensions to the JPA APIs:
+</p>
+<ul>
+    <li>{@link org.hibernate.query.criteria} packages extensions to {@link jakarta.persistence.criteria}, and</li>
+    <li>{@link org.hibernate.metamodel.model.domain} packages extensions to {@link jakarta.persistence.metamodel}.</li>
+</ul>
 
 <h3>Mapping annotations</h3>
 
@@ -132,6 +152,16 @@ mappings as an alternative.
     to use a tiny handful of them.
 </p>
 
+<h3>Annotations driving compile-time tooling</h3>
+
+<p>
+    The annotations defined by {@link org.hibernate.annotations.processing} instruct the Metamodel
+    Generator to {@linkplain org.hibernate.annotations.processing.CheckHQL validate HQL at compile
+    time}, and to automatically generate the implementation of
+    {@linkplain org.hibernate.annotations.processing.Find finder methods} and
+    {@linkplain org.hibernate.annotations.processing.HQL query methods}.
+<p>
+
 <h3>Popular extension points</h3>
 
 <p>