HHH-19508 improve jdoc of hibernate.order_updates and hibernate.order_inserts

Author: gavinking

hibernate-core/src/main/java/org/hibernate/cfg/BatchSettings.java

@@ -36,8 +36,13 @@ public interface BatchSettings {
 	String STATEMENT_BATCH_SIZE = "hibernate.jdbc.batch_size";
 
 	/**
-	 * Enable ordering of update statements by primary key value, for the purpose of more
-	 * efficient JDBC batching
+	 * Enable ordering of entity update statements by entity type and primary
+	 * key value, and of statements relating to collection modification by
+	 * collection role and foreign key value, for the purpose of more efficient
+	 * JDBC batching.
+	 * <p>
+	 * The sort order also reduces the change of a unique key violation when
+	 * a collection element is moved from one parent to a different parent.
 	 *
 	 * @see org.hibernate.boot.SessionFactoryBuilder#applyOrderingOfUpdates
 	 *
@@ -46,8 +51,11 @@ public interface BatchSettings {
 	String ORDER_UPDATES = "hibernate.order_updates";
 
 	/**
-	 * Enable ordering of insert statements by primary key value, for the purpose of more
-	 * efficient JDBC batching.
+	 * Enable ordering of entity insert statements by entity type and primary
+	 * key value, for the purpose of more efficient JDBC batching.
+	 * <p>
+	 * The sort order respects foreign key dependencies between entities, and
+	 * so also reduces the chance of a foreign key violation.
 	 *
 	 * @see org.hibernate.boot.SessionFactoryBuilder#applyOrderingOfInserts
 	 *