more jdoc for "minimal puts"

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

@@ -31,32 +31,46 @@ import jakarta.persistence.CacheStoreMode;
  * @see CacheRetrieveMode
  */
 public enum CacheMode {
+
 	/**
 	 * The session may read items from the cache, and add items to the cache
 	 * as it reads them from the database.
 	 */
 	NORMAL( CacheStoreMode.USE, CacheRetrieveMode.USE ),
+
 	/**
 	 * The session will never interact with the cache, except to invalidate
 	 * cached items when updates occur.
 	 */
 	IGNORE( CacheStoreMode.BYPASS, CacheRetrieveMode.BYPASS ),
+
 	/**
 	 * The session may read items from the cache, but will not add items,
 	 * except to invalidate items when updates occur.
 	 */
 	GET( CacheStoreMode.BYPASS, CacheRetrieveMode.USE ),
+
 	/**
 	 * The session will never read items from the cache, but will add items
 	 * to the cache as it reads them from the database. In this mode, the
 	 * value of the configuration setting
 	 * {@value org.hibernate.cfg.AvailableSettings#USE_MINIMAL_PUTS}
 	 * determines whether an item is written to the cache when the cache
-	 * already contains an entry with the same key.
+	 * already contains an entry with the same key. Minimal puts should be:
+	 * <ul>
+	 * <li>disabled for a cache where writes and reads carry a similar cost,
+	 *     as is usually the case for a local in-memory cache, and
+	 * <li>enabled for a cache where writes are much more expensive than
+	 *     reads, which is usually the case for a distributed cache.
+	 * </ul>
+	 * It's not usually necessary to specify this setting explicitly because,
+	 * by default, it's set to a sensible value by the second-level cache
+	 * implementation.
 	 *
-	 * @see org.hibernate.boot.SessionFactoryBuilder#applyStructuredCacheEntries(boolean)
+	 * @see org.hibernate.boot.SessionFactoryBuilder#applyMinimalPutsForCaching(boolean)
 	 */
 	PUT( CacheStoreMode.USE, CacheRetrieveMode.BYPASS ),
+
 	/**
 	 * As with to {@link #PUT}, the session will never read items from the
 	 * cache, but will add items to the cache as it reads them from the
@@ -65,7 +79,7 @@ public enum CacheMode {
 	 * bypassed, in order to <em>force</em> a refresh of a cached item,
 	 * even when an entry with the same key already exists in the cache.
 	 *
-	 * @see org.hibernate.boot.SessionFactoryBuilder#applyStructuredCacheEntries(boolean)
+	 * @see org.hibernate.boot.SessionFactoryBuilder#applyMinimalPutsForCaching(boolean)
 	 */
 	REFRESH( CacheStoreMode.REFRESH, CacheRetrieveMode.BYPASS );
 

hibernate-core/src/main/java/org/hibernate/boot/SessionFactoryBuilder.java

@@ -507,9 +507,9 @@ public interface SessionFactoryBuilder {
 	SessionFactoryBuilder applyDirectReferenceCaching(boolean enabled);
 
 	/**
-	 * When using bi-directional many-to-one associations and caching the one-to-many side
+	 * When using bidirectional many-to-one associations and caching the one-to-many side
 	 * it is expected that both sides of the association are managed (actually that is true of
-	 * all bi-directional associations).  However, in this case, if the user forgets to manage the
+	 * all bidirectional associations).  However, in this case, if the user forgets to manage the
 	 * one-to-many side stale data can be left in the second-level cache.
 	 * <p/>
 	 * Warning: enabling this will have a performance impact.  Hence why it is disabled by default

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

@@ -1312,14 +1312,21 @@ public interface AvailableSettings {
 
 	/**
 	 * Optimize interaction with the second-level cache to minimize writes, at the cost
-	 * of an additional read before each write.
+	 * of an additional read before each write. This setting is useful if writes to the
+	 * cache are much more expensive than reads from the cache, for example, if the cache
+	 * is a distributed cache.
+	 * <p>
+	 * It's not usually necessary to set this explicitly because, by default, it's set
+	 * to a {@linkplain org.hibernate.boot.SessionFactoryBuilder#applyMinimalPutsForCaching(boolean)
+	 * sensible value} by the second-level cache implementation.
 	 *
 	 * @see org.hibernate.boot.SessionFactoryBuilder#applyMinimalPutsForCaching(boolean)
 	 */
 	String USE_MINIMAL_PUTS = "hibernate.cache.use_minimal_puts";
 
 	/**
-	 * Enables the use of structured second-level cache entries.
+	 * Enables the use of structured second-level cache entries. This makes the cache
+	 * entries human-readable, but carries a performance cost.
 	 *
 	 * @see org.hibernate.boot.SessionFactoryBuilder#applyStructuredCacheEntries(boolean)
 	 */
@@ -1339,7 +1346,8 @@ public interface AvailableSettings {
 	 * Enable direct storage of entity references into the second level cache when
 	 * applicable. This is appropriate only for immutable entities.
 	 * <p>
-	 * By default, entities are always stored in a "disassembled" form.
+	 * By default, entities are always stored in a "disassembled" form, that is, as
+	 * a tuple of attribute values.
 	 *
 	 * @see org.hibernate.boot.SessionFactoryBuilder#applyDirectReferenceCaching(boolean)
 	 */