diff --git a/hibernate-reactive-core/src/main/java/org/hibernate/reactive/mutiny/Mutiny.java b/hibernate-reactive-core/src/main/java/org/hibernate/reactive/mutiny/Mutiny.java
index 71048e5b9..bee3a5c1f 100644
--- a/hibernate-reactive-core/src/main/java/org/hibernate/reactive/mutiny/Mutiny.java
+++ b/hibernate-reactive-core/src/main/java/org/hibernate/reactive/mutiny/Mutiny.java
@@ -2030,7 +2030,7 @@ interface SessionFactory extends AutoCloseable {
 
 
 		/**
-		 * Perform work using a {@link Session reactive session}.
+		 * Perform work using a {@linkplain Session reactive session}.
 		 * <p>
 		 * <il>
 		 * <li>If there is already a session associated with the current
@@ -2049,7 +2049,7 @@ interface SessionFactory extends AutoCloseable {
 		<T> Uni<T> withSession(Function<Session, Uni<T>> work);
 
 		/**
-		 * Perform work using a {@link Session reactive session} for
+		 * Perform work using a {@linkplain Session reactive session} for
 		 * a specified tenant.
 		 * <p>
 		 * <il>
@@ -2069,12 +2069,12 @@ interface SessionFactory extends AutoCloseable {
 		<T> Uni<T> withSession(String tenantId, Function<Session, Uni<T>> work);
 
 		/**
-		 * Perform work using a {@link Session reactive session} within an
-		 * associated {@link Transaction transaction}.
+		 * Perform work using a {@linkplain Session reactive session}
+		 * within an associated {@link Transaction transaction}.
 		 * <p>
 		 * <il>
-		 * <li>If there is already a session associated with the
-		 * current reactive stream, then the work will be executed using that
+		 * <li>If there is already a session associated with the current
+		 * reactive stream, then the work will be executed using that
 		 * session.
 		 * <li>Otherwise, if there is no session associated with the
 		 * current stream, a new session will be created.
@@ -2092,12 +2092,12 @@ interface SessionFactory extends AutoCloseable {
 		<T> Uni<T> withTransaction(BiFunction<Session, Transaction, Uni<T>> work);
 
 		/**
-		 * Perform work using a {@link Session reactive session} within an
-		 * associated transaction.
+		 * Perform work using a {@linkplain Session reactive session}
+		 * within an associated transaction.
 		 * <p>
 		 * <il>
-		 * <li>If there is already a session associated with the
-		 * current reactive stream, then the work will be executed using that
+		 * <li>If there is already a session associated with the current
+		 * reactive stream, then the work will be executed using that
 		 * session.
 		 * <li>Otherwise, if there is no session associated with the
 		 * current stream, a new session will be created.
@@ -2117,8 +2117,8 @@ default <T> Uni<T> withTransaction(Function<Session, Uni<T>> work) {
 		}
 
 		/**
-		 * Perform work using a {@link StatelessSession reactive session} within an
-		 * associated {@link Transaction transaction}.
+		 * Perform work using a {@linkplain StatelessSession reactive session}
+		 * within an associated {@link Transaction transaction}.
 		 * <p>
 		 * <il>
 		 * <li>If there is already a stateless session associated with the
@@ -2128,10 +2128,11 @@ default <T> Uni<T> withTransaction(Function<Session, Uni<T>> work) {
 		 * current stream, a new stateless session will be created.
 		 * </il>
 		 * <p>
-		 * The session will be closed automatically and the transaction committed automatically.
+		 * The session will be closed automatically and the transaction committed
+		 * automatically.
 		 *
-		 * @param work a function which accepts the stateless session and returns
-		 * the result of the work as a {@link Uni}.
+		 * @param work a function which accepts the stateless session and
+		 * returns the result of the work as a {@link Uni}.
 		 *
 		 * @see #withStatelessSession(Function)
 		 * @see StatelessSession#withTransaction(Function)
@@ -2141,8 +2142,8 @@ default <T> Uni<T> withStatelessTransaction(Function<StatelessSession, Uni<T>> w
 		}
 
 		/**
-		 * Perform work using a {@link StatelessSession reactive session} within an
-		 * associated {@link Transaction transaction}.
+		 * Perform work using a {@linkplain StatelessSession reactive session}
+		 * within an associated {@link Transaction transaction}.
 		 * <p>
 		 * <il>
 		 * <li>If there is already a stateless session associated with the
@@ -2152,7 +2153,8 @@ default <T> Uni<T> withStatelessTransaction(Function<StatelessSession, Uni<T>> w
 		 * current stream, a new stateless session will be created.
 		 * </il>
 		 * <p>
-		 * The session will be closed automatically and the transaction committed automatically.
+		 * The session will be closed automatically and the transaction committed
+		 * automatically.
 		 *
 		 * @param work a function which accepts the stateless session and returns
 		 * the result of the work as a {@link Uni}.
@@ -2163,7 +2165,7 @@ default <T> Uni<T> withStatelessTransaction(Function<StatelessSession, Uni<T>> w
 		<T> Uni<T> withStatelessTransaction(BiFunction<StatelessSession, Transaction, Uni<T>> work);
 
 		/**
-		 * Perform work using a {@link StatelessSession stateless session}.
+		 * Perform work using a {@linkplain StatelessSession stateless session}.
 		 * <p>
 		 * <il>
 		 * <li>If there is already a stateless session associated with the
@@ -2181,14 +2183,15 @@ default <T> Uni<T> withStatelessTransaction(Function<StatelessSession, Uni<T>> w
 		<T> Uni<T> withStatelessSession(Function<StatelessSession, Uni<T>> work);
 
 		/**
-		 * Perform work using a {@link StatelessSession stateless session}.
+		 * Perform work using a {@linkplain StatelessSession stateless session}.
 		 * <p>
 		 * <il>
 		 * <li>If there is already a stateless session associated with the
-		 * current reactive stream and given tenant id, then the work will be executed using that
-		 * session.
+		 * current reactive stream and given tenant id, then the work will be
+		 * executed using that session.
 		 * <li>Otherwise, if there is no stateless session associated with the
-		 * current stream and given tenant id, a new stateless session will be created.
+		 * current stream and given tenant id, a new stateless session will be
+		 * created.
 		 * </il>
 		 * <p>
 		 * The session will be closed automatically.
@@ -2200,15 +2203,17 @@ default <T> Uni<T> withStatelessTransaction(Function<StatelessSession, Uni<T>> w
 		<T> Uni<T> withStatelessSession(String tenantId, Function<StatelessSession, Uni<T>> work);
 
 		/**
-		 * Perform work using a {@link Session reactive session} for a
-		 * specified tenant within an associated {@link Transaction transaction}.
+		 * Perform work using a {@linkplain Session reactive session} for
+		 * the tenant with the specified tenant id within an associated
+		 * {@link Transaction transaction}.
 		 * <p>
 		 * <il>
-		 * <li>If there is already a session associated with the
-		 * current reactive stream and given tenant id, then the work will be executed using that
-		 * session.
+		 * <li>If there is already a session associated with the current
+		 * reactive stream and given tenant id, then the work will be
+		 * executed using that session.
 		 * <li>Otherwise, if there is no session associated with the
-		 * current stream and given tenant id, a new stateless session will be created.
+		 * current stream and given tenant id, a new stateless session
+		 * will be created.
 		 * </il>
 		 * <p>
 		 * The session will be {@link Session#flush() flushed} and closed
@@ -2224,18 +2229,21 @@ default <T> Uni<T> withStatelessTransaction(Function<StatelessSession, Uni<T>> w
 		<T> Uni<T> withTransaction(String tenantId, BiFunction<Session, Transaction, Uni<T>> work);
 
 		/**
-		 * Perform work using a {@link StatelessSession reactive session} for a
-		 * specified tenant within an associated {@link Transaction transaction}.
+		 * Perform work using a {@linkplain StatelessSession reactive session}
+		 * for the tenant with the specified tenant id within an associated
+		 * {@link Transaction transaction}.
 		 * <p>
 		 * <il>
 		 * <li>If there is already a stateless session associated with the
-		 * current reactive stream and given tenant id, then the work will be executed using that
-		 * session.
+		 * current reactive stream and given tenant id, then the work will be
+		 * executed using that session.
 		 * <li>Otherwise, if there is no stateless session associated with the
-		 * current stream and given tenant id, a new stateless session will be created.
+		 * current stream and given tenant id, a new stateless session will be
+		 * created.
 		 * </il>
 		 * <p>
-		 * The session will be closed automatically and the transaction committed automatically.
+		 * The session will be closed automatically and the transaction committed
+		 * automatically.
 		 *
 		 * @param tenantId the id of the tenant
 		 * @param work a function which accepts the stateless session and returns
diff --git a/hibernate-reactive-core/src/main/java/org/hibernate/reactive/mutiny/impl/MutinyStatelessSessionImpl.java b/hibernate-reactive-core/src/main/java/org/hibernate/reactive/mutiny/impl/MutinyStatelessSessionImpl.java
index 21602c48f..1f3600deb 100644
--- a/hibernate-reactive-core/src/main/java/org/hibernate/reactive/mutiny/impl/MutinyStatelessSessionImpl.java
+++ b/hibernate-reactive-core/src/main/java/org/hibernate/reactive/mutiny/impl/MutinyStatelessSessionImpl.java
@@ -300,6 +300,10 @@ public Mutiny.Transaction currentTransaction() {
 	private class Transaction<T> implements Mutiny.Transaction {
 		boolean rollback;
 
+		/**
+		 * Execute the given work in a new transaction. Called only
+		 * when no existing transaction was active.
+		 */
 		Uni<T> execute(Function<Mutiny.Transaction, Uni<T>> work) {
 			currentTransaction = this;
 			return begin()
@@ -308,14 +312,15 @@ Uni<T> execute(Function<Mutiny.Transaction, Uni<T>> work) {
 		}
 
 		/**
-		 * Run the code assuming that a transaction has already started so that we can
-		 * differentiate an error starting a transaction (and therefore doesn't need to rollback)
-		 * and an error thrown by the work.
+		 * Run the code assuming that a transaction has already started
+		 * so that we can differentiate an error starting a transaction
+		 * (which therefore does not need to trigger rollback) from an
+		 * error thrown by the work (which does).
 		 */
 		Uni<T> executeInTransaction(Function<Mutiny.Transaction, Uni<T>> work) {
 			return Uni.createFrom().deferred( () -> work.apply( this ) )
 					// in the case of an exception or cancellation
-					// we need to rollback the transaction
+					// we need to roll back the transaction
 					.onFailure().call( this::rollback )
 					.onCancellation().call( this::rollback )
 					// finally, when there was no exception,
diff --git a/hibernate-reactive-core/src/main/java/org/hibernate/reactive/stage/Stage.java b/hibernate-reactive-core/src/main/java/org/hibernate/reactive/stage/Stage.java
index a97b05e56..dccb3a072 100644
--- a/hibernate-reactive-core/src/main/java/org/hibernate/reactive/stage/Stage.java
+++ b/hibernate-reactive-core/src/main/java/org/hibernate/reactive/stage/Stage.java
@@ -1980,7 +1980,7 @@ interface Transaction {
 	interface SessionFactory extends AutoCloseable {
 
 		/**
-		 * Obtain a new {@link Session reactive session} {@link CompletionStage}, the main
+		 * Obtain a new {@linkplain Session reactive session} {@link CompletionStage}, the main
 		 * interaction point between the user's program and Hibernate
 		 * Reactive.
 		 * <p>
@@ -1994,7 +1994,7 @@ interface SessionFactory extends AutoCloseable {
 		CompletionStage<Session> openSession();
 
 		/**
-		 * Obtain a new {@link Session reactive session} {@link CompletionStage} for a
+		 * Obtain a new {@linkplain Session reactive session} {@link CompletionStage} for a
 		 * specified tenant.
 		 * <p>
 		 * When the {@link CompletionStage} completes successfully it returns a newly created session.
@@ -2033,7 +2033,7 @@ interface SessionFactory extends AutoCloseable {
 		CompletionStage<StatelessSession> openStatelessSession(String tenantId);
 
 		/**
-		 * Perform work using a {@link Session reactive session}.
+		 * Perform work using a {@linkplain Session reactive session}.
 		 * <p>
 		 * <il>
 		 * <li>If there is already a session associated with the current
@@ -2052,7 +2052,7 @@ interface SessionFactory extends AutoCloseable {
 		<T> CompletionStage<T> withSession(Function<Session, CompletionStage<T>> work);
 
 		/**
-		 * Perform work using a {@link Session reactive session} for a
+		 * Perform work using a {@linkplain Session reactive session} for a
 		 * specified tenant.
 		 * <p>
 		 * <il>
@@ -2072,7 +2072,7 @@ interface SessionFactory extends AutoCloseable {
 		<T> CompletionStage<T> withSession(String tenantId, Function<Session, CompletionStage<T>> work);
 
 		/**
-		 * Perform work using a {@link Session reactive session} within an
+		 * Perform work using a {@linkplain Session reactive session} within an
 		 * associated {@link Transaction transaction}.
 		 * <p>
 		 * <il>
@@ -2096,7 +2096,7 @@ interface SessionFactory extends AutoCloseable {
 		<T> CompletionStage<T> withTransaction(BiFunction<Session, Transaction, CompletionStage<T>> work);
 
 		/**
-		 * Perform work using a {@link Session reactive session} within an
+		 * Perform work using a {@linkplain Session reactive session} within an
 		 * associated transaction.
 		 * <p>
 		 * <il>
@@ -2121,15 +2121,17 @@ default <T> CompletionStage<T> withTransaction(Function<Session, CompletionStage
 		}
 
 		/**
-		 * Perform work using a {@link Session reactive session} for a
-		 * specified tenant within an associated {@link Transaction transaction}.
+		 * Perform work using a {@linkplain Session reactive session} for
+		 * the tenant with the specified tenant id within an associated
+		 * {@link Transaction transaction}.
 		 * <p>
 		 * <il>
-		 * <li>If there is already a session associated with the
-		 * current reactive stream and the given tenant, then the work will be executed using that
-		 * session.
-		 * <li>Otherwise, if there is no stateless session associated with the
-		 * current stream and the given tenant, a new stateless session will be created.
+		 * <li>If there is already a session associated with the current
+		 * reactive stream and given tenant id, then the work will be
+		 * executed using that session.
+		 * <li>Otherwise, if there is no stateless session associated with
+		 * the current stream and given tenant id, a new stateless session
+		 * will be created.
 		 * </il>
 		 * <p>
 		 * The session will be {@link Session#flush() flushed} and closed
@@ -2145,8 +2147,8 @@ default <T> CompletionStage<T> withTransaction(Function<Session, CompletionStage
 		<T> CompletionStage<T> withTransaction(String tenantId, BiFunction<Session, Transaction, CompletionStage<T>> work);
 
 		/**
-		 * Perform work using a {@link StatelessSession reactive session} within an
-		 * associated {@link Transaction transaction}.
+		 * Perform work using a {@linkplain StatelessSession reactive session}
+		 * within an associated {@link Transaction transaction}.
 		 * <p>
 		 * <il>
 		 * <li>If there is already a stateless session associated with the
@@ -2156,7 +2158,8 @@ default <T> CompletionStage<T> withTransaction(Function<Session, CompletionStage
 		 * current stream, a new stateless session will be created.
 		 * </il>
 		 * <p>
-		 * The session will be closed automatically, and the transaction committed automatically.
+		 * The session will be closed automatically, and the transaction committed
+		 * automatically.
 		 *
 		 * @param work a function which accepts the stateless session and returns
 		 *             the result of the work as a {@link CompletionStage}.
@@ -2169,8 +2172,8 @@ default <T> CompletionStage<T> withStatelessTransaction(Function<StatelessSessio
 		}
 
 		/**
-		 * Perform work using a {@link StatelessSession reactive session} within an
-		 * associated {@link Transaction transaction}.
+		 * Perform work using a {@linkplain StatelessSession reactive session}
+		 * within an associated {@link Transaction transaction}.
 		 * <p>
 		 * <il>
 		 * <li>If there is already a stateless session associated with the
@@ -2180,7 +2183,8 @@ default <T> CompletionStage<T> withStatelessTransaction(Function<StatelessSessio
 		 * current stream, a new stateless session will be created.
 		 * </il>
 		 * <p>
-		 * The session will be closed automatically, and the transaction committed automatically.
+		 * The session will be closed automatically, and the transaction committed
+		 * automatically.
 		 *
 		 * @param work a function which accepts the stateless session and returns
 		 *             the result of the work as a {@link CompletionStage}.
@@ -2191,18 +2195,21 @@ default <T> CompletionStage<T> withStatelessTransaction(Function<StatelessSessio
 		<T> CompletionStage<T> withStatelessTransaction(BiFunction<StatelessSession, Transaction, CompletionStage<T>> work);
 
 		/**
-		 * Perform work using a {@link StatelessSession reactive session} within an
-		 * associated {@link Transaction transaction}.
+		 * Perform work using a {@linkplain StatelessSession reactive session}
+		 * for the tenant with the specified tenant id within an associated
+		 * {@link Transaction transaction}.
 		 * <p>
 		 * <il>
 		 * <li>If there is already a stateless session associated with the
-		 * current reactive stream and the given tenant, then the work will be executed using that
-		 * session.
+		 * current reactive stream and given tenant id, then the work will be
+		 * executed using that session.
 		 * <li>Otherwise, if there is no stateless session associated with the
-		 * current stream, a new stateless session will be created.
+		 * current stream and given tenant id, a new stateless session will be
+		 * created.
 		 * </il>
 		 * <p>
-		 * The session will be closed automatically, and the transaction committed automatically.
+		 * The session will be closed automatically and the transaction committed
+		 * automatically.
 		 *
 		 * @param tenantId the id of the tenant
 		 * @param work a function which accepts the stateless session and returns
@@ -2214,7 +2221,7 @@ default <T> CompletionStage<T> withStatelessTransaction(Function<StatelessSessio
 		<T> CompletionStage<T> withStatelessTransaction(String tenantId, BiFunction<StatelessSession, Transaction, CompletionStage<T>> work);
 
 		/**
-		 * Perform work using a {@link StatelessSession stateless session}.
+		 * Perform work using a {@linkplain StatelessSession stateless session}.
 		 * <p>
 		 * <il>
 		 * <li>If there is already a stateless session associated with the
@@ -2232,7 +2239,7 @@ default <T> CompletionStage<T> withStatelessTransaction(Function<StatelessSessio
 		<T> CompletionStage<T> withStatelessSession(Function<StatelessSession, CompletionStage<T>> work);
 
 		/**
-		 * Perform work using a {@link StatelessSession stateless session}.
+		 * Perform work using a {@linkplain StatelessSession stateless session}.
 		 * <p>
 		 * <il>
 		 * <li>If there is already a stateless session associated with the