Refresh the javadoc of a bunch of annotations

Author: gavinking

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

@@ -7,13 +7,7 @@
 package org.hibernate;
 
 /**
- * Represents an association fetching strategy. This is used
- * together with the {@code Criteria} API to specify runtime
- * fetching strategies.
- * <p>
- * For HQL queries, use the {@code FETCH} keyword instead.
- *
- * @see Criteria#setFetchMode(String, FetchMode)
+ * Represents an association fetching strategy.
  *
  * @author Gavin King
  */

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

@@ -12,15 +12,17 @@
 import java.lang.annotation.Target;
 
 /**
- * Define the fetching strategy used for the given association.
+ * Specify the fetching strategy used for the annotated association.
  *
  * @author Emmanuel Bernard
+ *
+ * @see FetchMode
  */
 @Target({ElementType.METHOD, ElementType.FIELD})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Fetch {
 	/**
-	 * The style of fetch to use.
+	 * The method that should be used to fetch the association.
 	 */
 	FetchMode value();
 }

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

@@ -7,22 +7,27 @@
 package org.hibernate.annotations;
 
 /**
- * Fetch options on associations.  Defines more of the "how" of fetching, whereas JPA {@link jakarta.persistence.FetchType}
- * focuses on the "when".
+ * Enumerates the association fetching strategies available in Hibernate.
+ * <p>
+ * Whereas the JPA {@link jakarta.persistence.FetchType} enumeration provides a way to
+ * specify <em>when</em> an association should be fetched, this enumeration provides a
+ * way to express <em>how</em> it should be fetched.
  *
  * @author Emmanuel Bernard
  */
 public enum FetchMode {
 	/**
-	 * Use a secondary select for each individual entity, collection, or join load.
+	 * The association or collection is fetched with a separate subsequent SQL select.
 	 */
 	SELECT,
 	/**
-	 * Use an outer join to load the related entities, collections or joins.
+	 * The association or collection is fetched using an outer join clause added to
+	 * the initial SQL select.
 	 */
 	JOIN,
 	/**
-	 * Available for collections only.  When accessing a non-initialized collection, this fetch mode will trigger loading all elements of all collections of the same role for all owners associated with the persistence context using a single secondary select.
+	 * For collections and many-valued associations only. After the initial SQL select,
+	 * all associated collections are fetched together in a single subsequent select.
 	 */
 	SUBSELECT
 }

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

@@ -7,9 +7,15 @@
 package org.hibernate.annotations;
 
 /**
- * Enumeration extending jakarta.persistence flush modes.
+ * Enumeration extending {@link jakarta.persistence.FlushModeType JPA flush modes} with
+ * flush modes specific to Hibernate, and a "null" flush mode, {@link #PERSISTENCE_CONTEXT}
+ * for use as a default annotation value. Except for the null value, this enumeration is
+ * isomorphic to {@link org.hibernate.FlushMode}.
  *
  * @author Carlos Gonzalez-Cadenas
+ *
+ * @see NamedQuery
+ * @see NamedNativeQuery
  */
 public enum FlushModeType {
 	/**

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

@@ -5,28 +5,35 @@
  * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
  */
 package org.hibernate.annotations;
-import java.lang.annotation.ElementType;
+
+import java.lang.annotation.Target;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
+import static java.lang.annotation.ElementType.*;
+
 /**
- * Mark an Entity, a Collection, or an Attribute type as immutable. No annotation means the element is mutable.
- * <p>
- * An immutable entity may not be updated by the application. Updates to an immutable
- * entity will be ignored, but no exception is thrown. &#064;Immutable  must be used on root entities only. 
- * </p>
- * <p>
- * &#064;Immutable placed on a collection makes the collection immutable, meaning additions and 
- * deletions to and from the collection are not allowed. A <i>HibernateException</i> is thrown in this case. 
- * </p>
- * <p>
- * An immutable attribute type will not be copied in the currently running Persistence Context in order to detect if the underlying value is dirty. As a result loading the entity will require less memory
- * and checking changes will be much faster.
- * </p>
+ * Marks an entity, collection, or attribute as immutable. The absence of this annotation
+ * means the element is mutable.
+ * <ul>
+ * <li>
+ *     Changes made in memory to the state of an immutable entity are never synchronized to
+ *     the database. The changes are ignored, with no exception thrown. In a mapped inheritance
+ *     hierarchy, {@code @Immutable} may be applied only to the root entity.
+ * </li>
+ * <li>
+ *     An immutable collection may not be modified. A {@link org.hibernate.HibernateException}
+ *     is thrown if an element is added to or removed from the collection.
+ * </li>
+ * <li>
+ *     An immutable attribute is ignored by the dirty-checking process, and so the persistence
+ *     context does not need to keep track of its state. This may help reduce memory allocation.
+ * </li>
+ * </ul>
  *
  * @author Emmanuel Bernard
  */
-@java.lang.annotation.Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD})
+@Target({TYPE, METHOD, FIELD})
 @Retention( RetentionPolicy.RUNTIME )
 public @interface Immutable {
 }

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

@@ -21,7 +21,7 @@
  *
  * @see org.hibernate.query.Query
  */
-@Target( { TYPE, PACKAGE })
+@Target({TYPE, PACKAGE})
 @Retention(RUNTIME)
 @Repeatable(NamedQueries.class)
 public @interface NamedQuery {