completey rewrite the javadoc I just wrote and pushed

ooops, I suck :-(

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

@@ -29,26 +29,30 @@
  *     of the association.
  * </ul>
  * By default, an unfetched lazy association is represented
- * by a <em>proxy object</em>. This approach comes with the
+ * by a <em>proxy object</em> which holds the identifier
- * major advantage that the program may obtain the identifier
+ * (foreign key) of the associated entity instance.
- * (foreign key) of the associated entity instance without
+ * It's possible to obtain the identifier from an unfetched
- * fetching it from the database. Since a proxy carries a
+ * proxy, without fetching the entity from the database, by
- * foreign key, it's even possible to set an association
+ * calling the corresponding getter method. (It's even
- * using an unfetched proxy. On the other hand, for a
+ * possible to set an association to reference an unfetched
- * polymorphic association, the concrete type of the entity
+ * proxy.) Lazy fetching occurs when any other method of the
- * instance represented by a proxy is unknown, and so
+ * proxy is called. Once fetched, the proxy delegates all
- * {@link org.hibernate.Hibernate#getClass(Object)} must
+ * method invocations to the fetched entity instance.
+ * For a polymorphic association, the concrete type of the
+ * entity instance represented by a proxy is unknown, and
+ * so {@link org.hibernate.Hibernate#getClass(Object)} must
  * be used to obtain the concrete type, fetching the entity
- * by side effect.
+ * by side effect. Similarly, typecasts must be performed
+ * using {@link org.hibernate.Hibernate#unproxy(Object, Class)}.
  * <p>
- * With {@code LazyToOne(NO_PROXY)}, lazy fetching occurs
+ * With {@code LazyToOne(NO_PROXY)}, an associated entity
- * when the field holding the reference to the associated
+ * instance begins in an unloaded state, with only its
- * entity is accessed. With this approach, it's impossible
+ * identifier field set. Thus, it's possible to obtain the
- * to obtain the identifier of the associated entity without
+ * identifier if an unloaded entity, without triggering
- * fetching the entity from the database. On the other hand,
+ * lazy loading. Typecasts, {@code instanceof}, and
- * {@code instanceof} and {@link Object#getClass()} work as
+ * {@link Object#getClass()} work as normal. But this
- * normal, since the concrete type of the entity instance is
+ * option is only available when bytecode enhancement is
- * known immediately. This is usually bad tradeoff.
+ * used.
  * <p>
  * <strong>Currently, Hibernate does not support
  * {@code LazyToOne(NO_PROXY)} for polymorphic associations,

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

@@ -19,40 +19,52 @@
 public enum LazyToOneOption {
 	/**
 	 * The association is always loaded eagerly. The identifier
-	 * and concrete type of the associated entity instance are
+	 * and concrete type of the associated entity instance,
-	 * always known immediately.
+	 * along with all the rest of its non-lazy fields, are always
+	 * available immediately.
 	 */
 	FALSE,
 	/**
-	 * The association is proxied and loaded lazily, by
+	 * The association is proxied and a delegate entity instance
-	 * intercepting calls on the proxy object.
+	 * is lazily fetched when any method of the proxy other than
+	 * the getter method for the identifier property is first
+	 * called.
 	 * <ul>
-	 * <li>The program may obtain the entity identifier value
+	 * <li>The identifier property of the proxy object is set
+	 *     when the proxy is instantiated.
+	 *     The program may obtain the entity identifier value
 	 *     of an unfetched proxy, without triggering lazy
-	 *     fetching.
+	 *     fetching, by calling the corresponding getter method.
-	 * <li>For a polymorphic association, the proxy does not
+	 * <li>The proxy does not have the same concrete type as the
-	 *     have the concrete type of the proxied instance, and
+	 *     proxied delegate, and so
-	 *     so {@link org.hibernate.Hibernate#getClass(Object)}
+	 *     {@link org.hibernate.Hibernate#getClass(Object)}
-	 *     must be used in place of {@link Object#getClass()}
+	 *     must be used in place of {@link Object#getClass()}.
-	 *     and the Java {@code instanceof} operator.
+	 * <li>For a polymorphic association, the concrete type of
+	 *     the proxied entity instance is not known until the
+	 *     delegate is fetched from the database, and so
+	 *     {@link org.hibernate.Hibernate#unproxy(Object, Class)}}
+	 *     must be used to perform typecasts, and
+	 *     {@link org.hibernate.Hibernate#getClass(Object)}
+	 *     must be used instead of the Java {@code instanceof}
+	 *     operator.
 	 * </ul>
 	 */
 	PROXY,
 	/**
-	 * The association is loaded lazily when the field holding
+	 * The associated entity instance is initially in an unloaded
-	 * the reference to the associated object is first accessed.
+	 * state, and is loaded lazily when any field other than the
+	 * field containing the identifier is first accessed.
 	 * <ul>
-	 * <li>There is no way for the program to obtain the
+	 * <li>The identifier field of an unloaded entity instance is
-	 *     identifier of the associated entity without triggering
+	 *     set when the unloaded instance is instantiated.
-	 *     lazy fetching, and therefore this option is not
+	 *     The program may obtain the identifier of an unloaded
-	 *     recommended.
+	 *     entity, without triggering lazy fetching, by accessing
-	 * <li>On the other hand, {@link Object#getClass()} and the
+	 *     the field containing the identifier.
-	 *     {@code instanceof} operator may be used even if the
+	 * <li>Typecasts, the Java {@code instanceof} operator, and
-	 *     association is polymorphic.
+	 *     {@link Object#getClass()} may be used as normal.
+	 * <li>Bytecode enhancement is required. If the class is not
+	 *     enhanced, this option is equivalent to {@link #PROXY}.
 	 * </ul>
-	 * Bytecode enhancement is required. If the class is not
-	 * enhanced, this option is equivalent to {@link #PROXY}.
-	 * <p>
 	 * <strong>Currently, Hibernate does not support this setting
 	 * for polymorphic associations, and instead falls back to
 	 * {@link #PROXY}!</strong>