diff --git a/hibernate-core/src/main/java/org/hibernate/EnabledFetchProfile.java b/hibernate-core/src/main/java/org/hibernate/EnabledFetchProfile.java
index b26ed6b4c48f..2ea2858bb5bd 100644
--- a/hibernate-core/src/main/java/org/hibernate/EnabledFetchProfile.java
+++ b/hibernate-core/src/main/java/org/hibernate/EnabledFetchProfile.java
@@ -7,59 +7,60 @@
import jakarta.persistence.FindOption;
import org.hibernate.query.SelectionQuery;
-/**
- * A {@link jakarta.persistence.FindOption} which requests a named
- * {@linkplain org.hibernate.annotations.FetchProfile fetch profile}.
- *
- * 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}.
- *
- * For example, this class defines a fetch profile:
- *
- * An {@code EnabledFetchProfile} may be obtained from the static
- * metamodel for the entity {@code Book} and passed as an option to
- * {@link Session#find(Class, Object, FindOption...) find()}.
- *
- * When the static metamodel is not used, an {@code EnabledFetchProfile}
- * may be instantiated directly, passing the name of the fetch profile
- * as a string.
- *
- * Book bookWithAuthors =
- * session.find(Book.class, isbn,
- * new EnabledFetchProfile("WithAuthors"))
- *
- *
- * @param profileName the {@linkplain org.hibernate.annotations.FetchProfile#name profile name}
- *
- * @since 7.0
- *
- * @see org.hibernate.annotations.FetchProfile
- * @see Session#find(Class, Object, FindOption...)
- *
- * @author Gavin King
- */
+/// A [jakarta.persistence.FindOption] which represents a named
+/// [fetch profile][org.hibernate.annotations.FetchProfile].
+///
+/// An instance of this class may be obtained in a type safe way
+/// from the static metamodel for the class annotated with the
+/// [@FetchProfile][org.hibernate.annotations.FetchProfile].
+///
+/// For example, this class defines a fetch profile:
+/// ```java
+/// @Entity
+/// @FetchProfile(name = "WithAuthors")
+/// class Book {
+/// ...
+/// @ManyToMany
+/// @FetchProfileOverride(profile = Book_.PROFILE_WITH_AUTHORS)
+/// Set authors;
+/// }
+/// ```
+///
+/// An `EnabledFetchProfile` may be obtained from the static
+/// metamodel for the entity {@code Book} and passed as an option to
+/// [Session#find(Class, Object, FindOption...)].
+///
+/// ```java
+/// Book bookWithAuthors =
+/// session.find(Book.class, isbn, Book_._WithAuthors)
+/// ```
+///
+/// Alternatively, it may be [applied][#enable(Session)]
+/// to a `Session` or `Query`.
+///
+/// ```java
+/// Book_._WithAuthors.enable(session);
+/// Book bookWithAuthors = session.find(Book.class, isbn);
+/// ```
+///
+/// When the static metamodel is not used, an `EnabledFetchProfile`
+/// may be instantiated directly, passing the name of the fetch profile
+/// as a string.
+///
+/// ```java
+/// Book bookWithAuthors =
+/// session.find(Book.class, isbn,
+/// new EnabledFetchProfile("WithAuthors"))
+/// ```
+///
+/// @param profileName the [profile name][org.hibernate.annotations.FetchProfile#name].
+///
+/// @since 7.0
+///
+/// @see org.hibernate.annotations.FetchProfile
+/// @see Session#find(Class, Object, FindOption...)
+///
+/// @author Gavin King
public record EnabledFetchProfile(String profileName)
implements FindOption {
diff --git a/hibernate-core/src/main/java/org/hibernate/IdentifierLoadAccess.java b/hibernate-core/src/main/java/org/hibernate/IdentifierLoadAccess.java
index 6e544faaad54..a9b8f294371c 100644
--- a/hibernate-core/src/main/java/org/hibernate/IdentifierLoadAccess.java
+++ b/hibernate-core/src/main/java/org/hibernate/IdentifierLoadAccess.java
@@ -12,88 +12,73 @@
import jakarta.persistence.Timeout;
import org.hibernate.graph.GraphSemantic;
-/**
- * Loads an entity by its primary identifier.
- *
- * The interface is especially useful when customizing association
- * fetching using an {@link jakarta.persistence.EntityGraph}.
- *
- * It's also useful for loading entity instances with a specific
- * {@linkplain CacheMode cache interaction mode} in effect, or in
- * {@linkplain Session#setReadOnly(Object, boolean) read-only mode}.
- *
- * Book book =
- * session.byId(Book.class)
- * .with(CacheMode.GET)
- * .withReadOnly(true)
- * .load(bookId);
- *
- *
- * @author Eric Dalquist
- * @author Steve Ebersole
- *
- * @see Session#byId
- *
- * @deprecated Use forms of {@linkplain Session#find} accepting
- * {@linkplain jakarta.persistence.FindOption} instead of {@linkplain Session#byId}.
- */
+/// Loads an entity by its primary identifier.
+///
+/// The interface is especially useful when customizing association
+/// fetching using an [jakarta.persistence.EntityGraph].
+/// ```java
+/// var graph = session.createEntityGraph(Book.class);
+/// graph.addSubgraph(Book_.publisher);
+/// graph.addPluralSubgraph(Book_.authors)
+/// .addSubgraph(Author_.person);
+/// Book book = session.byId(Book.class)
+/// .withFetchGraph(graph)
+/// .load(bookId);
+/// ```
+///
+/// It's also useful for loading entity instances with a specific
+/// [cache interaction mode][CacheMode] in effect, or in
+/// [read-only mode][Session#setReadOnly(Object, boolean)].
+///
+/// ```java
+/// Book book = session.byId(Book.class)
+/// .with(CacheMode.GET)
+/// .withReadOnly(true)
+/// .load(bookId);
+/// ```
+///
+/// @author Eric Dalquist
+/// @author Steve Ebersole
+///
+/// @see Session#byId
+///
+/// @deprecated Use forms of [Session#find] accepting [jakarta.persistence.FindOption]} instead.
@Deprecated(since = "7.1", forRemoval = true)
public interface IdentifierLoadAccess {
- /**
- * Specify the {@linkplain LockMode lock mode} to use when
- * querying the database.
- *
- * @param lockMode The lock mode to apply
- * @return {@code this}, for method chaining
- */
+ /// Specify the [lock mode][LockMode] to use when querying the database.
+ ///
+ /// @param lockMode The lock mode to apply
+ ///
+ /// @return `this`, for method chaining
default IdentifierLoadAccess with(LockMode lockMode) {
return with( lockMode, PessimisticLockScope.NORMAL );
}
- /**
- * Specify the {@linkplain LockMode lock mode} to use when
- * querying the database.
- *
- * @param lockMode The lock mode to apply
- *
- * @return {@code this}, for method chaining
- */
+ /// Specify the [lock mode][LockMode] and [scope][PessimisticLockScope] to use when querying the database.
+ ///
+ /// @param lockMode The lock mode to apply
+ /// @param lockScope The locking scope (how much to lock).
+ ///
+ /// @return `this`, for method chaining
IdentifierLoadAccess with(LockMode lockMode, PessimisticLockScope lockScope);
- /**
- * Specify the {@linkplain Timeout timeout} to use when
- * querying the database.
- *
- * @param timeout The timeout to apply to the database operation
- *
- * @return {@code this}, for method chaining
- */
+ /// Specify the [timeout][Timeout] to use when querying the database.
+ ///
+ /// @param timeout The timeout to apply to the database operation
+ ///
+ /// @return `this`, for method chaining
IdentifierLoadAccess with(Timeout timeout);
- /**
- * Specify the {@linkplain LockOptions lock options} to use when
- * querying the database.
- *
- * @param lockOptions The lock options to use
- *
- * @return {@code this}, for method chaining
- *
- * @deprecated Use one of {@linkplain #with(LockMode)},
- * {@linkplain #with(LockMode, PessimisticLockScope)}
- * and/or {@linkplain #with(Timeout)} instead.
- */
+ /// Specify the [lock options][LockOptions] to use when querying the database.
+ ///
+ /// @param lockOptions The lock options to use
+ ///
+ /// @return `this`, for method chaining
+ ///
+ /// @deprecated Use one of [#with(LockMode)],
+ /// [#with(LockMode, PessimisticLockScope)]
+ /// and/or [#with(Timeout)] instead.
@Deprecated(since = "7.0", forRemoval = true)
IdentifierLoadAccess with(LockOptions lockOptions);
diff --git a/hibernate-core/src/main/java/org/hibernate/SessionBuilder.java b/hibernate-core/src/main/java/org/hibernate/SessionBuilder.java
index d6892e78b0bc..b5c8dc56b255 100644
--- a/hibernate-core/src/main/java/org/hibernate/SessionBuilder.java
+++ b/hibernate-core/src/main/java/org/hibernate/SessionBuilder.java
@@ -12,39 +12,38 @@
import org.hibernate.resource.jdbc.spi.PhysicalConnectionHandlingMode;
import org.hibernate.resource.jdbc.spi.StatementInspector;
-/**
- * Allows creation of a new {@link Session} with specific options
- * overriding the defaults from the {@link SessionFactory}.
- *