From 1d22d8e1742b656728c7141a7bb7159a69efbb55 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 | 24 ++++++++++++++++--
 release/src/release/javadoc/overview.html     | 25 ++++++++++++++++---
 2 files changed, 44 insertions(+), 5 deletions(-)

diff --git a/hibernate-core/src/main/javadoc/overview.html b/hibernate-core/src/main/javadoc/overview.html
index a1cd269ca3..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>
 
@@ -69,6 +72,13 @@
     {@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>
 
@@ -106,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 543e1b6175..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>
 
@@ -69,7 +72,13 @@
     {@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>
 
@@ -143,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>