From 80feb108fb2246eb83774aedc016e5f1aba83875 Mon Sep 17 00:00:00 2001
From: Gavin <gavin@hibernate.org>
Date: Wed, 24 May 2023 00:14:08 +0200
Subject: [PATCH] javadoc improvements

---
 .../org/hibernate/annotations/FetchProfile.java  |  5 +++--
 .../annotations/FetchProfileOverride.java        |  2 ++
 .../java/org/hibernate/annotations/View.java     |  3 +++
 .../org/hibernate/cfg/AvailableSettings.java     |  2 ++
 .../java/org/hibernate/query/SelectionQuery.java | 16 ++++++++++++++++
 5 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/FetchProfile.java b/hibernate-core/src/main/java/org/hibernate/annotations/FetchProfile.java
index b13bcb79b6..c92f772c16 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/FetchProfile.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/FetchProfile.java
@@ -27,8 +27,9 @@ import static org.hibernate.annotations.FetchMode.JOIN;
  * <p>
  * Additional fetch strategy overrides may be added to a named fetch
  * profile by annotating the fetched associations themselves with the
- * {@link FetchProfileOverride @Fetch} annotation, specifying the
- * {@linkplain FetchProfileOverride#profile name of the fetch profile}.
+ * {@link FetchProfileOverride @FetchProfileOverride} annotation,
+ * specifying the {@linkplain FetchProfileOverride#profile name of the
+ * fetch profile}.
  * <p>
  * A named fetch profile must be explicitly enabled in a given session
  * by calling {@link org.hibernate.Session#enableFetchProfile(String)}
diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/FetchProfileOverride.java b/hibernate-core/src/main/java/org/hibernate/annotations/FetchProfileOverride.java
index 1b7a7d4bae..7a4cc650c2 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/FetchProfileOverride.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/FetchProfileOverride.java
@@ -33,6 +33,8 @@ import static org.hibernate.annotations.FetchMode.JOIN;
  *
  * @author Gavin King
  *
+ * @since 6.3
+ *
  * @see FetchMode
  * @see FetchProfile
  * @see FetchProfile.FetchOverride
diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/View.java b/hibernate-core/src/main/java/org/hibernate/annotations/View.java
index f12972aeda..8f6495a1b3 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/View.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/View.java
@@ -7,6 +7,8 @@
 package org.hibernate.annotations;
 
 
+import org.hibernate.Incubating;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -62,6 +64,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  *
  * @author Gavin King
  */
+@Incubating
 @Target(TYPE)
 @Retention(RUNTIME)
 public @interface View {
diff --git a/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java b/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java
index c2a70a1a7c..bfa8c7a389 100644
--- a/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java
+++ b/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java
@@ -1045,6 +1045,8 @@ public interface AvailableSettings {
 	 * By default, Hibernate only uses subselect fetching for collections
 	 * explicitly annotated {@code @Fetch(SUBSELECT)}.
 	 *
+	 * @since 6.3
+	 *
 	 * @see org.hibernate.annotations.FetchMode#SUBSELECT
 	 * @see org.hibernate.Session#setSubselectFetchingEnabled(boolean)
 	 * @see org.hibernate.boot.SessionFactoryBuilder#applySubselectFetchEnabled(boolean)
diff --git a/hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java b/hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java
index 31fcae4e05..a20acd2adb 100644
--- a/hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java
+++ b/hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java
@@ -67,6 +67,20 @@ import org.hibernate.graph.GraphSemantic;
  *     {@link #setParameter(int, Object)} allow arguments to be bound to named
  *     and ordinal parameters defined by the query.
  * </ul>
+ * <p>
+ * A query may have explicit <em>fetch joins</em>, specified using the syntax
+ * {@code join fetch} in HQL, or via {@link jakarta.persistence.criteria.From#fetch}
+ * in the criteria API. Additional fetch joins may be added by:
+ * <ul>
+ * <li>setting an {@link EntityGraph} by calling
+ *     {@link #setEntityGraph(EntityGraph, GraphSemantic)}, or
+ * <li>enabling a fetch profile, using {@link Session#enableFetchProfile(String)}.
+ * </ul>
+ * The special built-in fetch profile named
+ * {@value org.hibernate.mapping.FetchProfile#HIBERNATE_DEFAULT_PROFILE} adds
+ * a fetch join for every {@link jakarta.persistence.FetchType#EAGER eager}
+ * {@code @ManyToOne} or {@code @OneToOne} association belonging to an entity
+ * returned by the query.
  *
  * @author Steve Ebersole
  */
@@ -193,6 +207,8 @@ public interface SelectionQuery<R> extends CommonQueryContract {
 	 * <p>
 	 * This is an alternative way to specify the associations which
 	 * should be fetched as part of the initial query.
+	 *
+	 * @since 6.3
 	 */
 	SelectionQuery<R> setEntityGraph(EntityGraph<R> graph, GraphSemantic semantic);