more info in javadoc of some generator annotations

Signed-off-by: Gavin King <gavin@hibernate.org>

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

@@ -17,14 +17,35 @@ import org.hibernate.generator.internal.CurrentTimestampGeneration;
  * Specifies that the annotated field of property is a generated <em>creation timestamp</em>.
  * The timestamp is generated just once, when an entity instance is inserted in the database.
  * <p>
- * By default, the timestamp is generated by {@linkplain java.time.Clock#instant() in memory},
+ * By default, the timestamp is generated by {@linkplain java.time.Clock#instant in memory},
  * but this may be changed by explicitly specifying the {@link #source}.
  * Otherwise, this annotation is a synonym for
  * {@link CurrentTimestamp @CurrentTimestamp(timing=INSERT,source=VM)}.
- *
- * @author Gunnar Morling
+ * <p>
+ * The annotated property may be of any one of the following types:
+ * {@link java.util.Date},
+ * {@link java.util.Calendar},
+ * {@link java.sql.Date},
+ * {@link java.sql.Time},
+ * {@link java.sql.Timestamp},
+ * {@link java.time.Instant},
+ * {@link java.time.LocalDate},
+ * {@link java.time.LocalDateTime},
+ * {@link java.time.LocalTime},
+ * {@link java.time.MonthDay},
+ * {@link java.time.OffsetDateTime},
+ * {@link java.time.OffsetTime},
+ * {@link java.time.Year},
+ * {@link java.time.YearMonth}, or
+ * {@link java.time.ZonedDateTime}.
+ * <p>
+ * A field annotated {@code @CreationTimestamp} may not be directly set by the application
+ * program.
  *
  * @see CurrentTimestamp
+ * @see UpdateTimestamp
+ *
+ * @author Gunnar Morling
  */
 @ValueGenerationType(generatedBy = CurrentTimestampGeneration.class)
 @Retention(RUNTIME)
@@ -32,7 +53,8 @@ import org.hibernate.generator.internal.CurrentTimestampGeneration;
 public @interface CreationTimestamp {
 	/**
 	 * Specifies how the timestamp is generated. By default, it is generated
-	 * in memory, which saves a round trip to the database.
+	 * in memory, which might save a round trip to the database, depending on
+	 * the capabilities of the database and JDBC driver.
 	 */
 	SourceType source() default SourceType.VM;
 }

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

@@ -19,18 +19,20 @@ import static org.hibernate.generator.EventType.UPDATE;
 
 /**
  * Specifies that the annotated field of property is a generated timestamp,
- * and also specifies the {@linkplain #event() timing} of the timestamp
+ * and also specifies the {@linkplain #event timing} of the timestamp
  * generation, and whether it is generated in Java or by the database:
  * <ul>
  * <li>{@link SourceType#VM source = VM} indicates that the virtual machine
- *     {@linkplain java.time.Clock#instant() current instant}
- *     is used, and
+ *     {@linkplain java.time.Clock#instant current instant} is used, and
  * <li>{@link SourceType#DB source = DB} indicates that the database
  *     {@code current_timestamp} function should be used.
  * </ul>
  * <p>
- * By default, the timestamp is generated by the database, which requires
- * an extra round trip to the database to fetch the generated value.
+ * By default, the timestamp is generated by the database, which might
+ * require an extra round trip to the database to fetch the generated
+ * value, depending on the capabilities of the
+ * {@linkplain org.hibernate.dialect.Dialect#supportsInsertReturning database} and
+ * {@linkplain org.hibernate.dialect.Dialect#supportsInsertReturningGeneratedKeys driver}.
  * <p>
  * This annotation may be used in combination with the JPA-defined
  * {@link jakarta.persistence.Version} annotation.
@@ -51,6 +53,9 @@ import static org.hibernate.generator.EventType.UPDATE;
  * {@link java.time.Year},
  * {@link java.time.YearMonth}, or
  * {@link java.time.ZonedDateTime}.
+ * <p>
+ * A field annotated {@code @CurrentTimestamp} may not be directly set
+ * by the application program.
  *
  * @see UpdateTimestamp
  * @see CreationTimestamp
@@ -74,7 +79,10 @@ public @interface CurrentTimestamp {
 
 	/**
 	 * Specifies how the timestamp is generated. By default, it is generated
-	 * by the database, and fetched using a subsequent {@code select} statement.
+	 * by the database. Depending on the capabilities of the database and JDBC
+	 * driver, this might require that the value be fetched using a subsequent
+	 * {@code select} statement. Setting {@code source = VM} guarantees that
+	 * this additional {@code select} never occurs.
 	 */
 	SourceType source() default SourceType.DB;
 }

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

@@ -15,9 +15,17 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Identifies a field of an entity that holds a tenant id
- * in discriminator-based multitenancy.
+ * Identifies a field of an entity that holds a tenant id in discriminator-based multitenancy.
+ * <p>
+ * A field annotated {@code @TenantId} is automatically set to the
+ * {@linkplain org.hibernate.SharedSessionContract#getTenantIdentifierValue current tenant id}
+ * when the entity is first made persistent. The {@code @TenantId} field may not be directly
+ * set by the application program.
+ * <p>
+ * If a {@code @TenantId} field is also annotated {@link jakarta.persistence.Id @Id}, it forms
+ * part of the composite primary key of the of an entity.
  *
+ * @see org.hibernate.SharedSessionContract#getTenantIdentifierValue
  * @see org.hibernate.context.spi.CurrentTenantIdentifierResolver
  *
  * @since 6.0

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

@@ -17,12 +17,33 @@ import org.hibernate.generator.internal.CurrentTimestampGeneration;
  * Specifies that the annotated field of property is a generated <em>update timestamp.</em>
  * The timestamp is regenerated every time an entity instance is updated in the database.
  * <p>
- * By default, the timestamp is generated {@linkplain java.time.Clock#instant() in memory},
+ * By default, the timestamp is generated {@linkplain java.time.Clock#instant in memory},
  * but this may be changed by explicitly specifying the {@link #source}.
  * Otherwise, this annotation is a synonym for
  * {@link CurrentTimestamp @CurrentTimestamp(source=VM)}.
+ * <p>
+ * The annotated property may be of any one of the following types:
+ * {@link java.util.Date},
+ * {@link java.util.Calendar},
+ * {@link java.sql.Date},
+ * {@link java.sql.Time},
+ * {@link java.sql.Timestamp},
+ * {@link java.time.Instant},
+ * {@link java.time.LocalDate},
+ * {@link java.time.LocalDateTime},
+ * {@link java.time.LocalTime},
+ * {@link java.time.MonthDay},
+ * {@link java.time.OffsetDateTime},
+ * {@link java.time.OffsetTime},
+ * {@link java.time.Year},
+ * {@link java.time.YearMonth}, or
+ * {@link java.time.ZonedDateTime}.
+ * <p>
+ * A field annotated {@code @UpdateTimestamp} may not be directly set by the application
+ * program.
  *
  * @see CurrentTimestamp
+ * @see CreationTimestamp
  *
  * @author Gunnar Morling
  */
@@ -32,7 +53,8 @@ import org.hibernate.generator.internal.CurrentTimestampGeneration;
 public @interface UpdateTimestamp {
 	/**
 	 * Specifies how the timestamp is generated. By default, it is generated
-	 * in memory, which saves a round trip to the database.
+	 * in memory, which might save a round trip to the database, depending on
+	 * the capabilities of the database and JDBC driver.
 	 */
 	SourceType source() default SourceType.VM;
 }