javadoc for LazyCollectionOption

Author: gavinking

hibernate-core/src/main/java/org/hibernate/annotations/LazyCollection.java

@@ -16,9 +16,10 @@
  * {@link jakarta.persistence.OneToMany} or
  * {@link jakarta.persistence.ManyToMany} association,
  * or an {@link jakarta.persistence.ElementCollection}.
- * <p>
  * This is an alternative to specifying the JPA
- * {@link jakarta.persistence.FetchType}.
+ * {@link jakarta.persistence.FetchType}. This annotation
+ * is used to enable {@linkplain LazyCollectionOption#EXTRA
+ * extra-lazy collection fetching}.
  *
  * @author Emmanuel Bernard
  */

hibernate-core/src/main/java/org/hibernate/annotations/LazyCollectionOption.java

@@ -7,21 +7,38 @@
 package org.hibernate.annotations;
 
 /**
- * Lazy options available for a collection.
+ *  Enumerates the options for lazy loading of a
+ *  {@linkplain jakarta.persistence.ElementCollection collection},
+ *  {@linkplain jakarta.persistence.ManyToOne many to one association},
+ *  or {@linkplain jakarta.persistence.ManyToMany many to many association}.
  *
  * @author Emmanuel Bernard
+ *
+ * @see LazyCollection
  */
 public enum LazyCollectionOption {
 	/**
-	 * Eagerly load it.
+	 * The collection is always loaded eagerly, and all its
+	 * elements are available immediately. However, access to
+	 * the collection is still mediated by an instance of
+	 * {@link org.hibernate.collection.spi.PersistentCollection},
+	 * which tracks modifications to the collection.
 	 */
 	FALSE,
 	/**
-	 * Load it when the state is requested.
+	 * The underlying Java collection is proxied by an instance of
+	 * {@link org.hibernate.collection.spi.PersistentCollection}
+	 * and lazily fetched when a method of the proxy is called.
+	 * All elements of the collection are retrieved at once.
 	 */
 	TRUE,
 	/**
-	 * Prefer extra queries over full collection loading.
+	 * The underlying Java collection is proxied by an instance of
+	 * {@link org.hibernate.collection.spi.PersistentCollection}
+	 * and its state is fetched lazily from the database as needed,
+	 * when methods of the proxy are called. When reasonable, the
+	 * proxy will avoid fetching all elements of the collection
+	 * at once.
 	 */
 	EXTRA
 }