From 1d12490dab235f5f1129dd9bd2a6224299295c05 Mon Sep 17 00:00:00 2001
From: Gavin King <gavin@hibernate.org>
Date: Tue, 27 Sep 2022 02:35:27 +0200
Subject: [PATCH] improve javadocs of @Source and @NotFound

---
 .../org/hibernate/annotations/NotFound.java   | 29 +++++++++++--------
 .../org/hibernate/annotations/Source.java     | 15 ++++++++--
 .../org/hibernate/annotations/SourceType.java | 27 ++++++++---------
 3 files changed, 43 insertions(+), 28 deletions(-)

diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/NotFound.java b/hibernate-core/src/main/java/org/hibernate/annotations/NotFound.java
index 50ca3fb329..eb8b9d1cec 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/NotFound.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/NotFound.java
@@ -14,24 +14,29 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Indicates that an association maps to a foreign key column without a
- * foreign key constraint, and which thus potentially violates referential
- * integrity.
+ * Indicates that a {@linkplain jakarta.persistence.ManyToOne many to one},
+ * {@linkplain jakarta.persistence.OneToOne one to one}, or
+ * {@linkplain jakarta.persistence.ManyToMany many to many} association
+ * maps to a column holding foreign keys, but without a foreign key
+ * constraint, and which may therefore violate referential integrity.
  * <p>
- * The {@link #action} specifies how Hibernate should handle the case of
- * an orphaned foreign key with no associated row in the referenced table.
+ * The {@link #action} specifies how Hibernate should handle violations of
+ * referential integrity, that is, the case of an orphaned foreign key with
+ * no associated row in the referenced table:
  * <ul>
- *     <li>{@link NotFoundAction#EXCEPTION} specifies that this situation
- *         should be treated as an error, and
- *     <li>{@link NotFoundAction#IGNORE} specifies that this situation
- *         should be treated as if the foreign key were null.
+ * <li>{@link NotFoundAction#EXCEPTION} specifies that this situation
+ *     should be treated as an error, causing a
+ *     {@link org.hibernate.exception.ConstraintViolationException}, and
+ * <li>{@link NotFoundAction#IGNORE} specifies that this situation should
+ *     be tolerated and treated as if the foreign key were null.
  * </ul>
- * Note that this annotation has the side effect of making the association
- * non-lazy.
+ * Note that this annotation has the side effect of making a to-one
+ * association non-lazy. It does not affect the laziness of a many-to-many
+ * association.
  * <p>
  * This annotation implies
  * {@link jakarta.persistence.ConstraintMode#NO_CONSTRAINT} for the purposes
- * of DDL generation. That is, a foreign key constraint will not be included
+ * of DDL generation. That is, no foreign key constraint will be included
  * in the generated DDL.
  *
  * @author Emmanuel Bernard
diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Source.java b/hibernate-core/src/main/java/org/hibernate/annotations/Source.java
index 1f060e0842..5cb1cff231 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/Source.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/Source.java
@@ -14,8 +14,16 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Optional annotation in conjunction with {@link jakarta.persistence.Version} and timestamp version properties
- * indicating the source of the timestamp value.
+ * Indicates the source of timestamps for an entity
+ * {@linkplain jakarta.persistence.Version version property} of
+ * type {@link java.sql.Timestamp}:
+ * <ul>
+ * <li>{@link SourceType#VM} indicates that the virtual machine
+ *     {@linkplain java.time.Clock#instant() current instance}
+ *     is used, and
+ * <li>{@link SourceType#DB} indicates that the database
+ *     {@code current_timestamp} function should be used.
+ * </ul>
  *
  * @author Hardy Ferentschik
  */
@@ -23,7 +31,8 @@
 @Retention(RUNTIME)
 public @interface Source {
 	/**
-	 * How is the timestamp generated?  Default is a JVM generated value.
+	 * The source of timestamps. By default, the {@linkplain
+	 * SourceType#VM virtual machine} is the source.
 	 */
 	SourceType value() default SourceType.VM;
 }
diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/SourceType.java b/hibernate-core/src/main/java/org/hibernate/annotations/SourceType.java
index 40f04cf5cd..bafbb3243a 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/SourceType.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/SourceType.java
@@ -7,33 +7,34 @@
 package org.hibernate.annotations;
 
 /**
- * Where should Hibernate retrieve the value from? From the database, or from the current JVM?
+ * Specifies the source of a generated {@link java.sql.Timestamp}.
+ * <p>
+ * Timestamps are generated by calling methods of
+ * {@link org.hibernate.type.descriptor.java.VersionJavaType}.
+ *
+ * @see Source
  *
  * @author Hardy Ferentschik
  */
 public enum SourceType {
 	/**
-	 * Get the timestamp from the current VM.
+	 * The virtual machine {@linkplain java.time.Clock#instant()
+	 * current instance} is the source of the generated timestamp.
 	 */
-	VM( "timestamp" ),
+	VM,
 
 	/**
-	 * Get the timestamp from the database.
+	 * The database {@code current_timestamp} function (or equivalent)
+	 * is the source of the generated timestamp.
 	 */
-	DB( "dbtimestamp" );
-
-	private final String typeName;
-
-	private SourceType(String typeName ) {
-		this.typeName = typeName;
-	}
+	DB;
 
 	/**
-	 * Get the corresponding Hibernate {@link org.hibernate.type.BasicType} name.
+	 * The corresponding {@link org.hibernate.type.BasicType} name.
 	 *
 	 * @return The corresponding type name.
 	 */
 	public String typeName() {
-		return typeName;
+		return this == SourceType.DB ? "dbtimestamp" : "timestamp";
 	}
 }