first round of Javadoc update to AvailableSettings

hibernate-core/src/main/java/org/hibernate/cache/spi/TimestampsCacheFactory.java

@@ -7,9 +7,12 @@
 package org.hibernate.cache.spi;
 
 /**
- * Responsible for building the TimestampsRegionAccessFactory to use for
- * managing query results in regards to staleness of the underlying
- * tables (sometimes called "query spaces" or "table spaces")
+ * Responsible for building the {@link TimestampsCache} to use for
+ * managing query results with respect to staleness of the underlying
+ * tables (sometimes called "query spaces" or "table spaces").
+ * <p>
+ * An implementation may be selected using the configuration property
+ * {@link org.hibernate.cfg.AvailableSettings#QUERY_CACHE_FACTORY}.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/engine/transaction/jta/platform/spi/JtaPlatform.java

@@ -33,14 +33,18 @@ import org.hibernate.service.Service;
 public interface JtaPlatform extends Service {
 
 	/**
-	 * Locate the {@link TransactionManager}
+	 * Locate the {@link TransactionManager}.
 	 *
 	 * @return The {@link TransactionManager}
 	 */
 	TransactionManager retrieveTransactionManager();
 
 	/**
-	 * Locate the {@link UserTransaction}
+	 * Locate the {@link UserTransaction}.
+	 * <p>
+	 * If {@link org.hibernate.cfg.AvailableSettings#PREFER_USER_TRANSACTION} is enabled, Hibernate
+	 * will use the {@code UserTransaction} in preference to the {@link TransactionManager} where
+	 * possible.
 	 *
 	 * @return The {@link UserTransaction}
 	 */