improve javadoc code examples in XxxxLoadAccess

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

@@ -19,8 +19,24 @@ import org.hibernate.graph.RootGraph;
  * <pre>
  * var graph = session.createEntityGraph(Book.class);
  * graph.addSubgraph(Book_.publisher);
- * graph.addPluralSubgraph(Book_.authors).addSubgraph(Author_.person);
+ * graph.addPluralSubgraph(Book_.authors)
- * session.byId(Book.class).withFetchGraph(graph).load(bookId);
+ *     .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

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

@@ -29,10 +29,10 @@ import static java.util.Collections.unmodifiableSet;
  * {@link Session#refresh(Object, LockOptions)}, the relevant options
  * are:
  * <ul>
- * <li>the {@link #getLockMode() lock mode},
+ * <li>the {@linkplain #getLockMode() lock mode},
- * <li>the {@link #getTimeOut() pessimistic lock timeout}, and
+ * <li>the {@linkplain #getTimeOut() pessimistic lock timeout}, and
- * <li>the {@link #getLockScope() lock scope}, that is, whether the
+ * <li>the {@linkplain #getLockScope() lock scope}, that is, whether
- *     lock extends to rows of owned collections.
+ *     the lock extends to rows of owned collections.
  * </ul>
  * <p>
  * Timeout and lock scope are ignored if the specified {@code LockMode}

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

@@ -15,10 +15,16 @@ import org.hibernate.graph.RootGraph;
  * Loads multiple instances of a given entity type at once, by
  * specifying a list of identifier values. This allows the entities
  * to be fetched from the database in batches.
+ * <p>
  * <pre>
  * var graph = session.createEntityGraph(Book.class);
  * graph.addSubgraph(Book_.publisher);
- * session.byId(Book.class).withFetchGraph(graph).multiLoad(bookIds);
+ *
+ * List&lt;Book&gt; books =
+ *         session.byId(Book.class)
+ *             .withFetchGraph(graph)
+ *             .withBatchSize(20)
+ *             .multiLoad(bookIds);
  * </pre>
  *
  * @see Session#byMultipleIds(Class)

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

@@ -19,6 +19,13 @@ import static org.hibernate.internal.util.collections.CollectionHelper.asMap;
  * specifying a list of natural id values. This allows the entities
  * to be fetched from the database in batches.
  * <p>
+ * <pre>
+ * List&lt;Book&gt; books =
+ *         session.byMultipleNaturalId(Book.class)
+ *             .withBatchSize(10)
+ *             .multiLoad(isbnList);
+ * </pre>
+ * <p>
  * Composite natural ids may be accommodated by passing a list of
  * maps of type {@code Map<String,Object>}  to {@link #multiLoad}.
  * Each map must contain the natural id attribute values keyed by
@@ -30,6 +37,7 @@ import static org.hibernate.internal.util.collections.CollectionHelper.asMap;
  * </pre>
  *
  * @see Session#byMultipleNaturalId(Class)
+ * @see org.hibernate.annotations.NaturalId
  */
 public interface NaturalIdMultiLoadAccess<T> {
 	/**

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

@@ -1303,6 +1303,7 @@ public interface Session extends SharedSessionContract, EntityManager {
 	 *
 	 * @see #setDefaultReadOnly(boolean)
 	 * @see Query#setReadOnly(boolean)
+	 * @see IdentifierLoadAccess#withReadOnly(boolean)
 	 *
 	 * @param entityOrProxy an entity or proxy
 	 * @param readOnly {@code true} if the entity or proxy should be made read-only;