expand javadoc for OptimisticLocking

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

@@ -26,6 +26,7 @@ import jakarta.persistence.LockModeType;
  * @see Session#lock(Object, LockMode)
  * @see LockModeType
  * @see LockOptions
+ * @see org.hibernate.annotations.OptimisticLocking
  */
 public enum LockMode {
 	/**

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

@@ -7,7 +7,7 @@
 package org.hibernate.annotations;
 
 /**
- * Possible optimistic locking strategies.
+ * Enumerates the possible optimistic lock checking strategies.
  *
  * @see OptimisticLocking
  *
@@ -15,25 +15,38 @@ package org.hibernate.annotations;
  */
 public enum OptimisticLockType {
 	/**
-	 * Perform no optimistic locking.
+	 * No optimistic locking.
 	 */
 	NONE,
 	/**
-	 * Perform optimistic locking using a dedicated version column.
+	 * Optimistic locking using a dedicated timestamp column or
+	 * {@linkplain jakarta.persistence.Version version column}.
+	 * This is the usual strategy.
+	 * <p>
+	 * Any SQL {@code update} or {@code delete} statement will
+	 * have a {@code where} clause restriction which specifies
+	 * the primary key and current version. If no rows are
+	 * updated, this is interpreted as a lock checking failure.
 	 *
 	 * @see jakarta.persistence.Version
 	 */
 	VERSION,
 	/**
-	 * Perform optimistic locking based on <em>dirty</em> fields as
-	 * part of an expanded {@code WHERE} clause restriction for the
-	 * SQL {@code UPDATE} or {@code DELETE} statement.
+	 * Optimistic locking based on <em>dirty</em> fields of the
+	 * entity.
+	 * <p>
+	 * A SQL {@code update} or {@code delete} statement will
+	 * have every dirty field of the entity instance listed in
+	 * the {@code where} clause restriction.
 	 */
 	DIRTY,
 	/**
-	 * Perform optimistic locking based on <em>all</em> fields as
-	 * part of an expanded {@code WHERE} clause restriction for the
-	 * SQL {@code UPDATE} or {@code DELETE} statement.
+	 * Optimistic locking based on <em>all</em> fields of the
+	 * entity.
+	 * <p>
+	 * A SQL {@code update} or {@code delete} statement will
+	 * have every field of the entity listed in the {@code where}
+	 * clause restriction.
 	 */
 	ALL
 }

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

@@ -13,17 +13,35 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Used to define the style of optimistic locking to be applied to an entity.
+ * Specifies how optimistic lock checking works for the annotated entity.
+ * We may detect that an optimistic lock has failed by checking either:
+ * <ul>
+ * <li>the {@linkplain OptimisticLockType#VERSION version or timestamp},
+ * <li>the {@linkplain OptimisticLockType#DIRTY dirty fields} of the
+ *     entity instance, or
+ * <li>{@linkplain OptimisticLockType#ALL all fields} of the entity.
+ * </ul>
+ * An optimistic lock is usually checked by including a restriction in a
+ * SQL {@code update} or {@code delete} statement. If the database reports
+ * that zero rows were updated, we may infer that another transaction has
+ * already updated or deleted the row, and report the {@linkplain
+ * jakarta.persistence.OptimisticLockException failure} of the optimistic
+ * lock.
+ * <p>
  * In an inheritance hierarchy, this annotation may only be applied to the
- * root entity.
+ * root entity, since the optimistic lock checking strategy is inherited
+ * by entity subclasses.
  *
  * @author Steve Ebersole
+ *
+ * @see org.hibernate.LockMode
+ * @see jakarta.persistence.LockModeType
  */
 @Target( TYPE )
 @Retention( RUNTIME )
 public @interface OptimisticLocking {
 	/**
-	 * Defines the style of optimistic locking for the entity.
+	 * The optimistic lock checking strategy.
 	 */
 	OptimisticLockType type() default OptimisticLockType.VERSION;
 }