HHH-16000 improve javadoc for @HQLSelect and @SQLSelect

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

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