properly document EnabledFetchProfile

Author: gavinking

documentation/src/main/asciidoc/introduction/Advanced.adoc

@@ -1140,14 +1140,21 @@ We may define as many different fetch profiles as we like.
 | `@FetchProfileOverride` | Specifies the fetch strategy for the annotated association, in a given fetch profile
 |===
 
-A fetch profile must be explicitly enabled for a given session by calling link:{doc-javadoc-url}org/hibernate/Session.html#enableFetchProfile(java.lang.String)[`enableFetchProfile()`]:
+A fetch profile must be explicitly enabled for a given session by passing the name of the profile to link:{doc-javadoc-url}org/hibernate/Session.html#enableFetchProfile(java.lang.String)[`enableFetchProfile()`]:
 
 [source,java]
 ----
 session.enableFetchProfile(Book_.PROFILE_EAGER_BOOK);
 Book eagerBook = session.find(Book.class, bookId);
 ----
 
+Alternatively, an instance of link:{doc-javadoc-url}org/hibernate/EnabledFetchProfile.html[`EnabledFetchProfile`] may be obtained in a type safe way from the static metamodel, and used as a `FindOption`:
+
+[source,java]
+----
+Book eagerBook = entityManager.find(Book.class, bookId, Book_._EagerBook);
+----
+
 So why or when might we prefer named fetch profiles to entity graphs?
 Well, it's really hard to say.
 It's nice that this feature _exists_, and if you love it, that's great.

hibernate-core/src/main/java/org/hibernate/EnabledFetchProfile.java

@@ -9,8 +9,41 @@
 /**
  * A {@link jakarta.persistence.FindOption} which requests a named
  * {@linkplain org.hibernate.annotations.FetchProfile fetch profile}.
+ * <p>
+ * An instance of this class may be obtained in a type safe way
+ * from the static metamodel for the class annotated
+ * {@link org.hibernate.annotations.FetchProfile @FetchProfile}
+ * and passed as an option to
+ * {@link Session#find(Class, Object, FindOption...) find()}.
+ * <p>
+ * For example, this class defines a fetch profile:
+ * <pre>
+ * &#064;Entity
+ * &#064;FetchProfile(name = "WithAuthors")
+ * class Book {
+ *     ...
  *
- * @param profileName the {@link org.hibernate.annotations.FetchProfile#name()}
+ *     &#064;ManyToMany
+ *     &#064;FetchProfileOverride(profile = Book_.PROFILE_WITH_AUTHORS)
+ *     Set&lt;Author&gt; authors;
+ * }
+ * </pre>
+ * The fetch profile may be requested like this:
+ * <pre>
+ * Book bookWithAuthors =
+ *         session.find(Book.class, isbn, Book_._WithAuthors)
+ * </pre>
+ * <p>
+ * When the static metamodel is not used, an {@code EnabledFetchProfile}
+ * may be instantiated directly, passing the name of the fetch profile
+ * as a string.
+ * <pre>
+ * Book bookWithAuthors =
+ *         session.find(Book.class, isbn,
+ *                      new EnabledFetchProfile("WithAuthors"))
+ * </pre>
+ *
+ * @param profileName the {@linkplain org.hibernate.annotations.FetchProfile#name profile name}
  *
  * @since 7.0
  *

hibernate-core/src/main/java/org/hibernate/annotations/FetchProfileOverride.java

@@ -54,8 +54,8 @@
 	FetchType fetch() default EAGER;
 
 	/**
-	 * The name of the {@link FetchProfile fetch profile} in
-	 * which this fetch mode should be applied.
+	 * The name of the {@linkplain FetchProfile fetch profile}
+	 * in which this fetch mode should be applied.
 	 */
 	String profile();
 }