HHH-19830 - Use of markdown for Javadoc

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}.
- * <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}.
- * <p>
- * For example, this class defines a fetch profile:
- * <pre>
- * &#064;Entity
- * &#064;FetchProfile(name = "WithAuthors")
- * class Book {
- *     ...
- *
- *     &#064;ManyToMany
- *     &#064;FetchProfileOverride(profile = Book_.PROFILE_WITH_AUTHORS)
- *     Set&lt;Author&gt; authors;
- * }
- * </pre>
- * <p>
- * 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()}.
- * <pre>
- * Book bookWithAuthors =
- *         session.find(Book.class, isbn, Book_._WithAuthors)
- * </pre>
- * Alternatively, it may be {@linkplain #enable(Session) applied}
- * to a {@code Session} or {@code Query}.
- * <pre>
- * Book_._WithAuthors.enable(session);
- * Book bookWithAuthors = session.find(Book.class, isbn);
- * </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
- *
- * @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<Author> 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 {
 

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.
- * <p>
- * The interface is especially useful when customizing association
- * fetching using an {@link jakarta.persistence.EntityGraph}.
- * <pre>
- * 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);
- * </pre>
- * <p>
- * 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}.
- * <pre>
- * Book book =
- *         session.byId(Book.class)
- *             .with(CacheMode.GET)
- *             .withReadOnly(true)
- *             .load(bookId);
- * </pre>
- *
- * @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<T> {
 
-	/**
-	 * 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<T> 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<T> 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<T> 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<T> with(LockOptions lockOptions);
 

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}.
- * <pre>
- * try (var session =
- *         sessionFactory.withOptions()
- *             .tenantIdentifier(tenantId)
- *             .initialCacheMode(CacheMode.PUT)
- *             .flushMode(FlushMode.COMMIT)
- *             .interceptor(new Interceptor() {
- *                 &#64;Override
- *                 public void preFlush(Iterator&lt;Object&gt; entities) {
- *                     ...
- *                 }
- *             })
- *             .openSession()) {
- *     ...
- * }
- * </pre>
- *
- * @author Steve Ebersole
- *
- * @see SessionFactory#withOptions()
- * @see SharedSessionBuilder
- */
+/// Allows creation of a new [Session] with specific options
+/// overriding the defaults from the [SessionFactory].
+///
+/// ```java
+/// try (var session = sessionFactory.withOptions()
+/// 		.tenantIdentifier(tenantId)
+/// 		.initialCacheMode(CacheMode.PUT)
+/// 		.flushMode(FlushMode.COMMIT)
+/// 		.interceptor(new Interceptor() {
+/// 			@Override
+/// 			public void preFlush(Iterator<Object> entities) {
+/// 				...
+/// 			}
+/// 		})
+/// 		.openSession()) {
+/// 			...
+/// 		}
+/// }
+/// @author Steve Ebersole
+///
+/// @see SessionFactory#withOptions()
+/// @see SharedSessionBuilder
 public interface SessionBuilder extends CommonBuilder {
-	/**
-	 * Opens a session with the specified options.
-	 *
-	 * @return The session
-	 */
+	/// Open the session using the specified options.
+	/// @see #open
 	Session openSession();
 
+	@Override
+	default Session open() {
+		return openSession();
+	}
+
 	@Override
 	SessionBuilder interceptor(Interceptor interceptor);