improve javadoc for session builders

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

@@ -13,11 +13,29 @@
 import org.hibernate.resource.jdbc.spi.StatementInspector;
 
 /**
- * Allows creation of a new {@link Session} with specific options.
+ * 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
  */
 public interface SessionBuilder extends CommonBuilder {
 	/**

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

@@ -13,11 +13,39 @@
 import java.util.function.UnaryOperator;
 
 /**
- * Specialized {@link SessionBuilder} with access to stuff from another session.
+ * Allows creation of a child {@link Session} which shares some options with
+ * another pre-existing parent session. Each session has its own isolated
+ * persistence context, and entity instances must not be shared between
+ * parent and child sessions.
+ * <p>
+ * When {@linkplain Transaction resource-local} transaction management is used:
+ * <ul>
+ * <li>by default, each session executes with its own dedicated JDBC connection
+ *     and therefore has its own isolated transaction, but
+ * <li>calling the {@link #connection()} method specifies that the connection,
+ *     and therefore also the JDBC transaction, should be shared from parent
+ *     to child.
+ * </ul>
+ * <p>
+ * <pre>
+ * try (var childSession
+ *          = session.sessionWithOptions()
+ *                  .connection() // share the JDBC connection
+ *                  .cacheMode(CacheMode.IGNORE)
+ *                  .openSession()) {
+ *     ...
+ * }
+ * </pre>
+ * <p>
+ * On the other hand, when JTA transaction management is used, all sessions
+ * execute within the same transaction. Typically, connection sharing is
+ * handled automatically by the JTA-enabled {@link javax.sql.DataSource}.
  *
  * @author Steve Ebersole
  *
  * @see Session#sessionWithOptions()
+ * @see StatelessSession#sessionWithOptions()
+ * @see SessionBuilder
  */
 public interface SharedSessionBuilder extends SessionBuilder, CommonSharedBuilder {
 

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

@@ -11,12 +11,35 @@
 import java.util.function.UnaryOperator;
 
 /**
- * Allows for creation of a {@linkplain StatelessSession stateless session} sharing the
- * underpinnings of another {@linkplain Session stateful} or {@linkplain StatelessSession stateless}
- * session.
+ * Allows creation of a child {@link StatelessSession} which shares some options
+ * with another pre-existing parent session.
+ * <p>
+ * When {@linkplain Transaction resource-local} transaction management is used:
+ * <ul>
+ * <li>by default, each session executes with its own dedicated JDBC connection
+ *     and therefore has its own isolated transaction, but
+ * <li>calling the {@link #connection()} method specifies that the connection,
+ *     and therefore also the JDBC transaction, should be shared from parent
+ *     to child.
+ * </ul>
+ * <p>
+ * <pre>
+ * try (var statelessSession
+ *          = session.statelessWithOptions()
+ *                  .connection() // share the JDBC connection
+ *                  .cacheMode(CacheMode.IGNORE)
+ *                  .openStatelessSession()) {
+ *     ...
+ * }
+ * </pre>
+ * <p>
+ * On the other hand, when JTA transaction management is used, all sessions
+ * execute within the same transaction. Typically, connection sharing is
+ * handled automatically by the JTA-enabled {@link javax.sql.DataSource}.
  *
  * @see Session#statelessWithOptions()
  * @see StatelessSession#statelessWithOptions()
+ * @see SharedSessionBuilder
  *
  * @since 7.2
  *

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

@@ -12,11 +12,13 @@
 import org.hibernate.resource.jdbc.spi.StatementInspector;
 
 /**
- * Allows creation of a new {@link StatelessSession} with specific options.
+ * Allows creation of a new {@link StatelessSession} with specific options
+ * overriding the defaults from the {@link SessionFactory}.
  *
  * @author Steve Ebersole
  *
  * @see SessionFactory#withStatelessOptions()
+ * @see SharedStatelessSessionBuilder
  */
 public interface StatelessSessionBuilder extends CommonBuilder {
 	/**

hibernate-core/src/main/java/org/hibernate/engine/creation/CommonBuilder.java

@@ -124,7 +124,15 @@ public interface CommonBuilder {
 	CommonBuilder noStatementInspector();
 
 	/**
-	 * Define the tenant identifier to be associated with the opened session.
+	 * Specify the tenant identifier to be associated with the opened session.
+	 * <pre>
+	 * try (var session =
+	 *         sessionFactory.withOptions()
+	 *             .tenantIdentifier(tenantId)
+	 *             .openSession()) {
+	 *     ...
+	 * }
+	 * </pre>
 	 *
 	 * @param tenantIdentifier The tenant identifier.
 	 *
@@ -160,6 +168,16 @@ public interface CommonBuilder {
 	 * possible to structure data access code in a way which eliminates
 	 * this possibility.
 	 * <p>
+	 * <pre>
+	 * try (var readOnlySession =
+	 *         sessionFactory.withOptions()
+	 *                 .readOnly(true)
+	 *                 .initialCacheMode(CacheMode.IGNORE)
+	 *                 .openSession()) {
+	 *     ...
+	 * }
+	 * </pre>
+	 * <p>
 	 * If a session is created in read-only mode, then it cannot be
 	 * changed to read-write mode, and any call to
 	 * {@link Session#setDefaultReadOnly(boolean)} with fail. On the