From 0007820abaeb532748c6f7b1ff8c180fd9ea3fc5 Mon Sep 17 00:00:00 2001
From: Gavin <gavin@hibernate.org>
Date: Sat, 7 Jan 2023 20:06:48 +0100
Subject: [PATCH] HHH-16000 improve javadoc for @HQLSelect and @SQLSelect

---
 .../java/org/hibernate/annotations/HQLSelect.java    | 12 ++++++++++--
 .../java/org/hibernate/annotations/SQLSelect.java    | 10 +++++++++-
 2 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/HQLSelect.java b/hibernate-core/src/main/java/org/hibernate/annotations/HQLSelect.java
index 7abc0bd587..3da87ef4ea 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/HQLSelect.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/HQLSelect.java
@@ -16,8 +16,14 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
  * Specifies a custom HQL/JPQL query to be used in place of the default SQL
- * generated by Hibernate when an entity or collection is loaded from the
- * database.
+ * generated by Hibernate when an entity or collection is fetched from the
+ * database by id. This occurs when:
+ * <ul>
+ * <li>an association to an entity is fetched lazily,
+ * <li>a collection is fetched lazily, or
+ * <li>when an entity is retrieved using {@link org.hibernate.Session#get}
+ *     or {@link org.hibernate.Session#find}.
+ * </ul>
  * <p>
  * The given {@linkplain #query HQL query} must have exactly one parameter
  * which accepts the {@linkplain jakarta.persistence.Id id} of the entity
@@ -25,6 +31,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * in the select list, and that item must be the correct type of entity or
  * collection element.
  *
+ * @see SQLSelect
+ *
  * @author Gavin King
  *
  * @since 6.2
diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/SQLSelect.java b/hibernate-core/src/main/java/org/hibernate/annotations/SQLSelect.java
index b4aeaef997..721519874b 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/SQLSelect.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/SQLSelect.java
@@ -19,7 +19,13 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 /**
  * Specifies a custom SQL query to be used in place of the default SQL
  * generated by Hibernate when an entity or collection is loaded from the
- * database.
+ * database by id. This occurs when:
+ * <ul>
+ * <li>an association to an entity is fetched lazily,
+ * <li>a collection is fetched lazily, or
+ * <li>when an entity is retrieved using {@link org.hibernate.Session#get}
+ *     or {@link org.hibernate.Session#find}.
+ * </ul>
  * <p>
  * The given {@linkplain #sql SQL statement} must have exactly the number
  * of JDBC {@code ?} parameters that Hibernate expects, that is, one for
@@ -44,6 +50,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  *     of basic-typed values.
  * </ol>
  *
+ * @see HQLSelect
+ *
  * @author Gavin King
  *
  * @since 6.2