explain effect of LockModes on lost updates and non-repeatable reads

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

@@ -34,6 +34,34 @@
  * which any pessimistic lock is already held has no effect,
  * and does not force a version increment.
  * <p>
+ * When an entity is read from the database, its lock mode
+ * determines whether lost updates and non-repeatable reads are
+ * possible. Assuming the underlying transaction isolation
+ * {@linkplain java.sql.Connection#getTransactionIsolation level}
+ * of the current JDBC database connection is at least
+ * {@linkplain java.sql.Connection#TRANSACTION_READ_COMMITTED
+ * read committed}, then:
+ * <ul>
+ * <li>{@link #NONE} and {@link #READ} prevent lost updates
+ *     only for versioned entities, but do not prevent
+ *     non-repeatable reads, and do not prevent lost updates
+ *     for entities with no version attribute;
+ * <li>{@link #OPTIMISTIC} and {@link #OPTIMISTIC_FORCE_INCREMENT}
+ *     prevent lost updates and non-repeatable reads only for
+ *     versioned entities;
+ * <li>{@link #PESSIMISTIC_READ}, {@link #PESSIMISTIC_WRITE},
+ *     and {@link #PESSIMISTIC_FORCE_INCREMENT} prevent lost
+ *     updates and non-repeatable reads for all entities,
+ *     including entities with no version attribute.
+ * </ul>
+ * <p>
+ * Regardless of the lock mode of a given entity, a non-repeatable
+ * read is always possible when {@link Session#refresh(Object)}
+ * is called for that entity, except when the underlying transaction
+ * isolation level of the current JDBC database connection is at
+ * least {@linkplain java.sql.Connection#TRANSACTION_REPEATABLE_READ
+ * repeatable read}.
+ * <p>
  * This enumeration of lock modes competes with the JPA-defined
  * {@link LockModeType}, but offers additional options, including
  * {@link #UPGRADE_NOWAIT} and {@link #UPGRADE_SKIPLOCKED}.