From dbe2c5451e123eaca74ab748158058f1ec883c0d Mon Sep 17 00:00:00 2001
From: Gavin King <gavin@hibernate.org>
Date: Wed, 7 Feb 2024 11:48:51 +0100
Subject: [PATCH] more blurb about finder/query methods

---
 .../annotations/processing/package-info.java  | 27 +++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)

diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/processing/package-info.java b/hibernate-core/src/main/java/org/hibernate/annotations/processing/package-info.java
index 76ebc5a2e6..367d3b0ac7 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/processing/package-info.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/processing/package-info.java
@@ -21,8 +21,31 @@
  * </ul>
  * <p>
  * Annotations in this package control Hibernate's compile-time
- * tooling. For example, this code defines a DAO-style repository
- * object:
+ * tooling, and depend on the use of the annotation processors
+ * in the {@code hibernate-jpamodelgen} or {@code query-validator}
+ * modules. If the appropriate annotation processor is not enabled
+ * at build time, these annotations have no effect.
+ * <p>
+ * Finder methods and query methods are usually declared by an
+ * interface, say {@code Queries}, and their implementations
+ * are generated into a class whose name follows the convention
+ * of the JPA static metamodel, that is, {@code Queries_}.
+ * <ul>
+ * <li>If the interface declares a method which returns an
+ *     {@code EntityManager}, Hibernate session, stateless
+ *     session, or reactive session, the generated class
+ *     implements the interface, {@code class Queries_ implements
+ *     Queries}, the generated methods are instance methods, and
+ *     the session must be provided to the class constructor,
+ *     possibly via dependency injection.
+ * <li>Otherwise, if there is no such method, the generated class
+ *     is non-instantiable, {@code abstract class Queries_}, the
+ *     generated methods are declared {@code static}, and the
+ *     session must be provided as an argument by the caller of
+ *     the generated methods.
+ * </ul>
+ * <p>
+ * For example, this code defines a DAO-style repository object:
  * <pre>
  * package org.example;
  *