deprecate @Target which dupes functionality of JPA annotations

...and refresh some misc annotation javadoc

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

@@ -11,7 +11,7 @@ import jakarta.persistence.CacheRetrieveMode;
 import jakarta.persistence.CacheStoreMode;
 
 /**
- * Controls how the session interacts with the {@link Cache second-level cache}
+ * Controls how the session interacts with the {@linkplain Cache second-level cache}
  * or {@linkplain org.hibernate.query.SelectionQuery#isCacheable() query cache}.
  * An instance of {@code CacheMode} may be viewed as packaging a JPA-defined
  * {@link CacheStoreMode} with a {@link CacheRetrieveMode}. For example,

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

@@ -16,10 +16,11 @@ import java.lang.annotation.Target;
 import org.hibernate.tuple.CreationTimestampGeneration;
 
 /**
- * Marks a property as the creation timestamp of the containing entity. The property value will be set to the current
- * VM date exactly once when saving the owning entity for the first time.
+ * Marks a property as the creation timestamp of the containing entity.
+ * The property value is set to the current VM datetime when the owning
+ * entity is made persistent for the first time.
  * <p>
- * Supported property types:
+ * The annotated field or property must be of one of the following types:
  * <ul>
  * <li>{@link java.util.Date}</li>
  * <li>{@link java.util.Calendar}</li>

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

@@ -7,8 +7,8 @@
 package org.hibernate.annotations;
 
 /**
- * Enumeration extending {@link jakarta.persistence.FlushModeType JPA flush modes} with
- * flush modes specific to Hibernate, and a "null" flush mode, {@link #PERSISTENCE_CONTEXT}
+ * Enumeration extending the {@linkplain jakarta.persistence.FlushModeType JPA flush modes}
+ * with flush modes specific to Hibernate, and a "null" 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}.
  *

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

@@ -17,7 +17,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  *
  * @author Emmanuel Bernard
  *
- * @deprecated Using {@link jakarta.persistence.Index} instead.
+ * @deprecated Use {@link jakarta.persistence.Index} instead.
  */
 @Target({FIELD, METHOD})
 @Retention(RUNTIME)

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

@@ -20,7 +20,7 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Used to specify a {@link MutabilityPlan} for a basic value mapping.
+ * Specifies a {@link MutabilityPlan} for a basic value mapping.
  * <ul>
  *     <li>
  *         When applied to a Map-valued attribute, describes the

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

@@ -13,7 +13,8 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Lazy and proxy configuration of a particular class.
+ * Allows the proxy class of an entity class to be explicitly specified.
+ * This annotation is almost never useful.
  *
  * @author Emmanuel Bernard
  */
@@ -21,12 +22,12 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Retention(RUNTIME)
 public @interface Proxy {
 	/**
-	 * Whether this class is lazy or not.  Default to true.
+	 * Whether this class may be proxied.  Default to true.
 	 */
 	boolean lazy() default true;
 
 	/**
-	 * Proxy class or interface used.  Default is to use the entity class name.
+	 * Proxy class or interface used.  Default is to the annotated entity class itself.
 	 */
 	Class<?> proxyClass() default void.class;
 }

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

@@ -14,6 +14,11 @@ package org.hibernate.annotations;
  * the expected number of rows.
  *
  * @author L<EFBFBD>szl<EFBFBD> Benke
+ *
+ * @see SQLInsert#check()
+ * @see SQLUpdate#check()
+ * @see SQLDelete#check()
+ * @see SQLDeleteAll#check()
  */
 public enum ResultCheckStyle {
 	/**

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

@@ -13,10 +13,12 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Ensures that auto-flush happens correctly and that queries against the derived 
- * entity do not return stale data.
- * 
- * Mostly used with {@link Subselect}.
+ * Specifies the tables that hold state mapped by the annotated derived
+ * entity, ensuring that auto-flush happens correctly and that queries
+ * against the derived entity do not return stale data.
+ * <p>
+ * This annotation may be used in combination with {@link Subselect}, or
+ * when an entity maps a database view.
  * 
  * @author Sharath Reddy
  */
@@ -24,7 +26,9 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Retention(RUNTIME)
 public @interface Synchronize {
 	/**
-	 * Table names.
+	 * Names of tables that hold state mapped by the derived entity.
+	 * Updates to these tables must be flushed to the database before
+	 * the derived entity is queried.
 	 */
 	String[] value();
 }

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

@@ -11,10 +11,17 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
 /**
- * Define an explicit target, avoiding reflection and generics resolving.
+ * Explicitly specifies the target entity type in an association,
+ * avoiding reflection and generics resolution. This annotation is
+ * almost never useful.
  *
  * @author Emmanuel Bernard
+ *
+ * @deprecated use annotation members of JPA association mapping
+ *             annotations, for example,
+ *             {@link jakarta.persistence.OneToMany#targetEntity()}
  */
+@Deprecated
 @java.lang.annotation.Target({ElementType.FIELD, ElementType.METHOD})
 @Retention( RetentionPolicy.RUNTIME )
 public @interface Target {

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

@@ -16,10 +16,11 @@ import java.lang.annotation.Target;
 import org.hibernate.tuple.UpdateTimestampGeneration;
 
 /**
- * Marks a property as the update timestamp of the containing entity. The property value will be set to the current VM
- * date whenever the owning entity is updated.
+ * Marks a property as the update timestamp of the containing entity.
+ * The property value will be set to the current VM datetime whenever
+ * the owning entity is updated.
  * <p>
- * Supported property types:
+ * The annotated field or property must be of one of the following types:
  * <ul>
  * <li>{@link java.util.Date}</li>
  * <li>{@link java.util.Calendar}</li>

hibernate-core/src/main/java/org/hibernate/annotations/package-info.java

@@ -6,7 +6,7 @@
  */
 
 /**
- * Package containing all Hibernate's specific annotations.
+ * A set of mapping annotations which extend the O/R mapping annotations defined by JPA.
  *
  * <h3 id="basic-value-mapping">Basic value mapping</h3>
  *
@@ -41,6 +41,6 @@
  * the compositional approach.  Though the compositional approach is recommended, both forms are
  * fully supported.
  *
- * See the user-guide for a more in-depth discussion
+ * Please see the user guide for a more in-depth discussion.
  */
 package org.hibernate.annotations;