Add missing javadocs and fix rest of Checkstyle failures

hibernate-infinispan/src/main/java/org/hibernate/cache/infinispan/InfinispanRegionFactory.java

@@ -90,6 +90,12 @@ public class InfinispanRegionFactory implements RegionFactory {
 	 */
 	public static final String INFINISPAN_CONFIG_RESOURCE_PROP = "hibernate.cache.infinispan.cfg";
 
+   /**
+    * Property name that controls whether Infinispan statistics are enabled.
+    * The property value is expected to be a boolean true or false, and it
+    * overrides statistic configuration in base Infinispan configuration,
+    * if provided.
+    */
 	public static final String INFINISPAN_GLOBAL_STATISTICS_PROP = "hibernate.cache.infinispan.statistics";
 
 	/**

hibernate-infinispan/src/main/java/org/hibernate/cache/infinispan/TypeOverrides.java

@@ -69,6 +69,12 @@ public class TypeOverrides {
 		return evictionStrategy;
 	}
 
+   /**
+    * Sets eviction strategy for cached type.
+    *
+    * @param evictionStrategy String defining eviction strategy allowed.
+    *                         Possible values are defined in {@link EvictionStrategy}
+    */
 	public void setEvictionStrategy(String evictionStrategy) {
 		markAsOverriden( "evictionStrategy" );
 		this.evictionStrategy = EvictionStrategy.valueOf( uc( evictionStrategy ) );
@@ -78,6 +84,13 @@ public class TypeOverrides {
 		return evictionWakeUpInterval;
 	}
 
+   /**
+    * Sets how often eviction process should be run for the cached type.
+    *
+    * @param evictionWakeUpInterval long representing the frequency for executing
+    *                               the eviction process, in milliseconds
+    *
+    */
 	public void setEvictionWakeUpInterval(long evictionWakeUpInterval) {
 		markAsOverriden( "evictionWakeUpInterval" );
 		this.evictionWakeUpInterval = evictionWakeUpInterval;
@@ -87,6 +100,14 @@ public class TypeOverrides {
 		return evictionMaxEntries;
 	}
 
+   /**
+    * Maximum number of entries in a cache for this cached type. Cache size
+    * is guaranteed  not to exceed upper limit specified by max entries.
+    * However, due to the nature of eviction it is unlikely to ever be
+    * exactly maximum number of entries specified here.
+    *
+    * @param evictionMaxEntries number of maximum cache entries
+    */
 	public void setEvictionMaxEntries(int evictionMaxEntries) {
 		markAsOverriden( "evictionMaxEntries" );
 		this.evictionMaxEntries = evictionMaxEntries;
@@ -96,6 +117,14 @@ public class TypeOverrides {
 		return expirationLifespan;
 	}
 
+   /**
+    * Maximum lifespan of a cache entry, after which the entry is expired
+    * cluster-wide, in milliseconds. -1 means the entries never expire.
+    *
+    * @param expirationLifespan long representing the maximum lifespan,
+    *                           in milliseconds, for a cached entry before
+    *                           it's expired
+    */
 	public void setExpirationLifespan(long expirationLifespan) {
 		markAsOverriden( "expirationLifespan" );
 		this.expirationLifespan = expirationLifespan;
@@ -105,6 +134,15 @@ public class TypeOverrides {
 		return expirationMaxIdle;
 	}
 
+   /**
+    * Maximum idle time a cache entry will be maintained in the cache, in
+    * milliseconds. If the idle time is exceeded, the entry will be expired
+    * cluster-wide. -1 means the entries never expire.
+    *
+    * @param expirationMaxIdle long representing the maximum idle time, in
+    *                          milliseconds, for a cached entry before it's
+    *                          expired
+    */
 	public void setExpirationMaxIdle(long expirationMaxIdle) {
 		markAsOverriden( "expirationMaxIdle" );
 		this.expirationMaxIdle = expirationMaxIdle;
@@ -114,11 +152,24 @@ public class TypeOverrides {
 		return isExposeStatistics;
 	}
 
+   /**
+    * Enable statistics gathering and reporting via JMX.
+    *
+    * @param isExposeStatistics boolean indicating whether statistics should
+    *                           be enabled or disabled
+    */
 	public void setExposeStatistics(boolean isExposeStatistics) {
 		markAsOverriden( "isExposeStatistics" );
 		this.isExposeStatistics = isExposeStatistics;
 	}
 
+   /**
+    * Apply the configuration overrides in this {@link TypeOverrides} instance
+    * to the cache configuration builder passed as parameter.
+    *
+    * @param builder cache configuration builder on which to apply
+    *                configuration overrides
+    */
 	public void applyTo(ConfigurationBuilder builder) {
 		if ( overridden.contains( "evictionStrategy" ) ) {
 			builder.eviction().strategy( evictionStrategy );
@@ -140,6 +191,12 @@ public class TypeOverrides {
 		}
 	}
 
+   /**
+    * Validate the configuration for this cached type.
+    *
+    * @param cfg configuration to validate
+    * @throws CacheException if validation fails
+    */
 	public void validateInfinispanConfiguration(Configuration cfg) throws CacheException {
 		// no-op, method overriden
 	}

hibernate-infinispan/src/main/java/org/hibernate/cache/infinispan/access/PutFromLoadValidator.java

@@ -89,7 +89,6 @@ public class PutFromLoadValidator {
 	 * {@link #acquirePutFromLoadLock(Object)} that hasn't been
 	 * {@link #registerPendingPut(Object) pre-registered} (aka a "naked put")
 	 * will return false.
-	 * will return false.
 	 */
 	public static final long NAKED_PUT_INVALIDATION_PERIOD = TimeUnit.SECONDS.toMillis( 20 );
 
@@ -128,7 +127,9 @@ public class PutFromLoadValidator {
 	private volatile long invalidationTimestamp;
 
 	/**
-	 * Creates a new PutFromLoadValidator.
+	 * Creates a new put from load validator instance.
+    *
+    * @param cache Cache instance on which to store pending put information.
 	 */
 	public PutFromLoadValidator(AdvancedCache cache) {
 		this( cache, NAKED_PUT_INVALIDATION_PERIOD );
@@ -136,6 +137,12 @@ public class PutFromLoadValidator {
 
    /**
     * Constructor variant for use by unit tests; allows control of various timeouts by the test.
+    *
+    * @param cache Cache instance on which to store pending put information.
+    * @param nakedPutInvalidationPeriod Period (in ms) after a removal during which a call to
+    *                                   {@link #acquirePutFromLoadLock(Object)} that hasn't been
+    *                                   {@link #registerPendingPut(Object) pre-registered} (aka a "naked put")
+    *                                   will return false.
     */
 	public PutFromLoadValidator(
 			AdvancedCache cache,
@@ -146,6 +153,16 @@ public class PutFromLoadValidator {
 		);
 	}
 
+   /**
+    * Creates a new put from load validator instance.
+    *
+    * @param cacheManager where to find a cache to store pending put information
+    * @param tm transaction manager
+    * @param nakedPutInvalidationPeriod Period (in ms) after a removal during which a call to
+    *                                   {@link #acquirePutFromLoadLock(Object)} that hasn't been
+    *                                   {@link #registerPendingPut(Object) pre-registered} (aka a "naked put")
+    *                                   will return false.
+    */
 	public PutFromLoadValidator(
 			EmbeddedCacheManager cacheManager,
 			TransactionManager tm, long nakedPutInvalidationPeriod) {

hibernate-infinispan/src/main/java/org/hibernate/cache/infinispan/access/TransactionalAccessDelegate.java

@@ -32,7 +32,6 @@ import org.infinispan.util.logging.LogFactory;
 import org.hibernate.cache.CacheException;
 import org.hibernate.cache.infinispan.impl.BaseRegion;
 import org.hibernate.cache.infinispan.util.Caches;
-import org.hibernate.cache.spi.access.SoftLock;
 
 /**
  * Defines the strategy for transactional access to entity or collection data in a Infinispan instance.
@@ -53,6 +52,12 @@ public class TransactionalAccessDelegate {
 	private final PutFromLoadValidator putValidator;
 	private final AdvancedCache<Object, Object> writeCache;
 
+   /**
+    * Create a new transactional access delegate instance.
+    *
+    * @param region to control access to
+    * @param validator put from load validator
+    */
 	public TransactionalAccessDelegate(BaseRegion region, PutFromLoadValidator validator) {
 		this.region = region;
 		this.cache = region.getCache();
@@ -60,21 +65,50 @@ public class TransactionalAccessDelegate {
 		this.writeCache = Caches.ignoreReturnValuesCache( cache );
 	}
 
+   /**
+    * Attempt to retrieve an object from the cache.
+    *
+    * @param key The key of the item to be retrieved
+    * @param txTimestamp a timestamp prior to the transaction start time
+    * @return the cached object or <tt>null</tt>
+    * @throws CacheException if the cache retrieval failed
+    */
 	public Object get(Object key, long txTimestamp) throws CacheException {
 		if ( !region.checkValid() ) {
 			return null;
 		}
-		Object val = cache.get( key );
+		final Object val = cache.get( key );
 		if ( val == null ) {
 			putValidator.registerPendingPut( key );
 		}
 		return val;
 	}
 
+   /**
+    * Attempt to cache an object, after loading from the database.
+    *
+    * @param key The item key
+    * @param value The item
+    * @param txTimestamp a timestamp prior to the transaction start time
+    * @param version the item version number
+    * @return <tt>true</tt> if the object was successfully cached
+    */
 	public boolean putFromLoad(Object key, Object value, long txTimestamp, Object version) {
 		return putFromLoad( key, value, txTimestamp, version, false );
 	}
 
+   /**
+    * Attempt to cache an object, after loading from the database, explicitly
+    * specifying the minimalPut behavior.
+    *
+    * @param key The item key
+    * @param value The item
+    * @param txTimestamp a timestamp prior to the transaction start time
+    * @param version the item version number
+    * @param minimalPutOverride Explicit minimalPut flag
+    * @return <tt>true</tt> if the object was successfully cached
+    * @throws CacheException if storing the object failed
+    */
 	public boolean putFromLoad(Object key, Object value, long txTimestamp, Object version, boolean minimalPutOverride)
 			throws CacheException {
 		if ( !region.checkValid() ) {
@@ -110,20 +144,16 @@ public class TransactionalAccessDelegate {
 		return true;
 	}
 
-	public SoftLock lockItem(Object key, Object version) throws CacheException {
+   /**
-		return null;
+    * Called after an item has been inserted (before the transaction completes),
-	}
+    * instead of calling evict().
-
+    *
-	public SoftLock lockRegion() throws CacheException {
+    * @param key The item key
-		return null;
+    * @param value The item
-	}
+    * @param version The item's version value
-
+    * @return Were the contents of the cache actual changed by this operation?
-	public void unlockItem(Object key, SoftLock lock) throws CacheException {
+    * @throws CacheException if the insert fails
-	}
+    */
-
-	public void unlockRegion(SoftLock lock) throws CacheException {
-	}
-
 	public boolean insert(Object key, Object value, Object version) throws CacheException {
 		if ( !region.checkValid() ) {
 			return false;
@@ -133,10 +163,17 @@ public class TransactionalAccessDelegate {
 		return true;
 	}
 
-	public boolean afterInsert(Object key, Object value, Object version) throws CacheException {
+   /**
-		return false;
+    * Called after an item has been updated (before the transaction completes),
-	}
+    * instead of calling evict().
-
+    *
+    * @param key The item key
+    * @param value The item
+    * @param currentVersion The item's current version value
+    * @param previousVersion The item's previous version value
+    * @return Whether the contents of the cache actual changed by this operation
+    * @throws CacheException if the update fails
+    */
 	public boolean update(Object key, Object value, Object currentVersion, Object previousVersion)
 			throws CacheException {
 		// We update whether or not the region is valid. Other nodes
@@ -146,11 +183,12 @@ public class TransactionalAccessDelegate {
 		return true;
 	}
 
-	public boolean afterUpdate(Object key, Object value, Object currentVersion, Object previousVersion, SoftLock lock)
+   /**
-			throws CacheException {
+    * Called after an item has become stale (before the transaction completes).
-		return false;
+    *
-	}
+    * @param key The key of the item to remove
-
+    * @throws CacheException if removing the cached item fails
+    */
 	public void remove(Object key) throws CacheException {
 		if ( !putValidator.invalidateKey( key ) ) {
 			throw new CacheException(
@@ -163,6 +201,11 @@ public class TransactionalAccessDelegate {
 		writeCache.remove( key );
 	}
 
+   /**
+    * Called to evict data from the entire region
+    *
+    * @throws CacheException if eviction the region fails
+    */
 	public void removeAll() throws CacheException {
 		if ( !putValidator.invalidateRegion() ) {
 			throw new CacheException( "Failed to invalidate pending putFromLoad calls for region " + region.getName() );
@@ -170,6 +213,13 @@ public class TransactionalAccessDelegate {
 		cache.clear();
 	}
 
+   /**
+    * Forcibly evict an item from the cache immediately without regard for transaction
+    * isolation.
+    *
+    * @param key The key of the item to remove
+    * @throws CacheException if evicting the item fails
+    */
 	public void evict(Object key) throws CacheException {
 		if ( !putValidator.invalidateKey( key ) ) {
 			throw new CacheException(
@@ -179,6 +229,12 @@ public class TransactionalAccessDelegate {
 		writeCache.remove( key );
 	}
 
+   /**
+    * Forcibly evict all items from the cache immediately without regard for transaction
+    * isolation.
+    *
+    * @throws CacheException if evicting items fails
+    */
 	public void evictAll() throws CacheException {
 		if ( !putValidator.invalidateRegion() ) {
 			throw new CacheException( "Failed to invalidate pending putFromLoad calls for region " + region.getName() );

hibernate-infinispan/src/main/java/org/hibernate/cache/infinispan/collection/CollectionRegionImpl.java

@@ -35,18 +35,29 @@ import org.hibernate.cache.spi.access.AccessType;
 import org.hibernate.cache.spi.access.CollectionRegionAccessStrategy;
 
 /**
+ * Collection region implementation
+ *
  * @author Chris Bredesen
  * @author Galder Zamarreño
  * @since 3.5
  */
 public class CollectionRegionImpl extends BaseTransactionalDataRegion implements CollectionRegion {
 
+   /**
+    * Construct a collection region
+    *
+    * @param cache instance to store collection instances
+    * @param name of collection type
+    * @param metadata for the collection type
+    * @param factory for the region
+    */
 	public CollectionRegionImpl(
 			AdvancedCache cache, String name,
 			CacheDataDescription metadata, RegionFactory factory) {
 		super( cache, name, metadata, factory );
 	}
 
+	@Override
 	public CollectionRegionAccessStrategy buildAccessStrategy(AccessType accessType) throws CacheException {
 		if ( AccessType.READ_ONLY.equals( accessType )
 				|| AccessType.TRANSACTIONAL.equals( accessType ) ) {

hibernate-infinispan/src/main/java/org/hibernate/cache/infinispan/entity/EntityRegionImpl.java

@@ -35,12 +35,22 @@ import org.hibernate.cache.spi.access.AccessType;
 import org.hibernate.cache.spi.access.EntityRegionAccessStrategy;
 
 /**
+ * Entity region implementation
+ *
  * @author Chris Bredesen
  * @author Galder Zamarreño
  * @since 3.5
  */
 public class EntityRegionImpl extends BaseTransactionalDataRegion implements EntityRegion {
 
+   /**
+    * Construct a entity region
+    *
+    * @param cache instance to store entity instances
+    * @param name of entity type
+    * @param metadata for the entity type
+    * @param factory for the region
+    */
 	public EntityRegionImpl(
 			AdvancedCache cache, String name,
 			CacheDataDescription metadata, RegionFactory factory) {

hibernate-infinispan/src/main/java/org/hibernate/cache/infinispan/impl/BaseGeneralDataRegion.java

@@ -17,6 +17,13 @@ import org.hibernate.cache.spi.RegionFactory;
 public abstract class BaseGeneralDataRegion extends BaseRegion implements GeneralDataRegion {
 	private final AdvancedCache putCache;
 
+   /**
+    * General data region constructor.
+    *
+    * @param cache instance for the region
+    * @param name of the region
+    * @param factory for this region
+    */
 	public BaseGeneralDataRegion(
 			AdvancedCache cache, String name,
 			RegionFactory factory) {

hibernate-infinispan/src/main/java/org/hibernate/cache/infinispan/impl/BaseRegion.java

@@ -68,6 +68,13 @@ public abstract class BaseRegion implements Region {
 
 	protected final AdvancedCache cache;
 
+   /**
+    * Base region constructor.
+    *
+    * @param cache instance for the region
+    * @param name of the region
+    * @param factory for this region
+    */
 	public BaseRegion(AdvancedCache cache, String name, RegionFactory factory) {
 		this.cache = cache;
 		this.name = name;
@@ -147,6 +154,12 @@ public abstract class BaseRegion implements Region {
 		return checkValid() && cache.containsKey( key );
 	}
 
+   /**
+    * Checks if the region is valid for operations such as storing new data
+    * in the region, or retrieving data from the region.
+    *
+    * @return true if the region is valid, false otherwise
+    */
 	public boolean checkValid() {
 		boolean valid = isValid();
 		if ( !valid ) {
@@ -154,7 +167,7 @@ public abstract class BaseRegion implements Region {
 				if ( invalidateState.compareAndSet(
 						InvalidateState.INVALID, InvalidateState.CLEARING
 				) ) {
-					Transaction tx = suspend();
+					final Transaction tx = suspend();
 					try {
 						// Clear region in a separate transaction
 						Caches.withinTx(
@@ -228,6 +241,9 @@ public abstract class BaseRegion implements Region {
 		}
 	}
 
+   /**
+    * Invalidates the region.
+    */
 	public void invalidateRegion() {
 		if ( log.isTraceEnabled() ) {
 			log.trace( "Invalidate region: " + name );

hibernate-infinispan/src/main/java/org/hibernate/cache/infinispan/impl/BaseTransactionalDataRegion.java

@@ -41,6 +41,14 @@ public abstract class BaseTransactionalDataRegion
 
 	private final CacheDataDescription metadata;
 
+   /**
+    * Base transactional region constructor
+    *
+    * @param cache instance to store transactional data
+    * @param name of the transactional region
+    * @param metadata for the transactional region
+    * @param factory for the transactional region
+    */
 	public BaseTransactionalDataRegion(
 			AdvancedCache cache, String name,
 			CacheDataDescription metadata, RegionFactory factory) {

hibernate-infinispan/src/main/java/org/hibernate/cache/infinispan/naturalid/NaturalIdRegionImpl.java

@@ -43,6 +43,14 @@ import org.hibernate.cache.spi.access.NaturalIdRegionAccessStrategy;
 public class NaturalIdRegionImpl extends BaseTransactionalDataRegion
 		implements NaturalIdRegion {
 
+   /**
+    * Constructor for the natural id region.
+    *
+    * @param cache instance to store natural ids
+    * @param name of natural id region
+    * @param metadata for the natural id region
+    * @param factory for the natural id region
+    */
 	public NaturalIdRegionImpl(
 			AdvancedCache cache, String name,
 			CacheDataDescription metadata, RegionFactory factory) {

hibernate-infinispan/src/main/java/org/hibernate/cache/infinispan/query/QueryResultsRegionImpl.java

@@ -35,6 +35,8 @@ import org.hibernate.cache.spi.QueryResultsRegion;
 import org.hibernate.cache.spi.RegionFactory;
 
 /**
+ * Region for caching query results.
+ *
  * @author Chris Bredesen
  * @author Galder Zamarreño
  * @since 3.5
@@ -45,6 +47,13 @@ public class QueryResultsRegionImpl extends BaseTransactionalDataRegion implemen
 	private final AdvancedCache putCache;
 	private final AdvancedCache getCache;
 
+   /**
+    * Query region constructor
+    *
+    * @param cache instance to store queries
+    * @param name of the query region
+    * @param factory for the query region
+    */
 	public QueryResultsRegionImpl(AdvancedCache cache, String name, RegionFactory factory) {
 		super( cache, name, null, factory );
 		// If Infinispan is using INVALIDATION for query cache, we don't want to propagate changes.

hibernate-infinispan/src/main/java/org/hibernate/cache/infinispan/timestamp/ClusteredTimestampsRegionImpl.java

@@ -56,6 +56,13 @@ public class ClusteredTimestampsRegionImpl extends TimestampsRegionImpl {
 	 */
 	private final Map localCache = new ConcurrentHashMap();
 
+   /**
+    * Clustered timestamps region constructor.
+    *
+    * @param cache instance to store update timestamps
+    * @param name of the update timestamps region
+    * @param factory for the update timestamps region
+    */
 	public ClusteredTimestampsRegionImpl(
 			AdvancedCache cache,
 			String name, RegionFactory factory) {

hibernate-infinispan/src/main/java/org/hibernate/cache/infinispan/timestamp/TimestampsRegionImpl.java

@@ -46,6 +46,13 @@ public class TimestampsRegionImpl extends BaseGeneralDataRegion implements Times
 	private final AdvancedCache removeCache;
 	private final AdvancedCache timestampsPutCache;
 
+   /**
+    * Local timestamps region constructor.
+    *
+    * @param cache instance to store update timestamps
+    * @param name of the update timestamps region
+    * @param factory for the update timestamps region
+    */
 	public TimestampsRegionImpl(
 			AdvancedCache cache, String name,
 			RegionFactory factory) {

hibernate-infinispan/src/main/java/org/hibernate/cache/infinispan/tm/HibernateTransactionManagerLookup.java

@@ -28,7 +28,8 @@ import org.hibernate.cfg.Settings;
 import org.hibernate.engine.transaction.jta.platform.spi.JtaPlatform;
 
 /**
- * HibernateTransactionManagerLookup.
+ * Hibernate transaction manager lookup class for Infinispan, so that
+ * Hibernate's transaction manager can be hooked onto Infinispan.
  *
  * @author Galder Zamarreño
  * @since 3.5
@@ -36,6 +37,12 @@ import org.hibernate.engine.transaction.jta.platform.spi.JtaPlatform;
 public class HibernateTransactionManagerLookup implements org.infinispan.transaction.lookup.TransactionManagerLookup {
 	private final JtaPlatform jtaPlatform;
 
+   /**
+    * Transaction manager lookup constructor.
+    *
+    * @param settings for the Hibernate application
+    * @param properties for the Hibernate application
+    */
 	public HibernateTransactionManagerLookup(Settings settings, Properties properties) {
 		this.jtaPlatform = settings != null ? settings.getJtaPlatform() : null;
 	}

hibernate-infinispan/src/main/java/org/hibernate/cache/infinispan/util/CacheCommandFactory.java

@@ -42,13 +42,29 @@ import org.hibernate.cache.infinispan.impl.BaseRegion;
  * @since 4.0
  */
 public class CacheCommandFactory implements ExtendedModuleCommandFactory {
+
+   /**
+    * Keeps track of regions to which second-level cache specific
+    * commands have been plugged.
+    */
 	private ConcurrentMap<String, BaseRegion> allRegions =
 			new ConcurrentHashMap<String, BaseRegion>();
 
+   /**
+    * Add region so that commands can be cleared on shutdown.
+    *
+    * @param regionName name of the region
+    * @param region instance to keep track of
+    */
 	public void addRegion(String regionName, BaseRegion region) {
 		allRegions.put( regionName, region );
 	}
 
+   /**
+    * Clear all regions from this command factory.
+    *
+    * @param regionNames collection of regions to clear
+    */
 	public void clearRegions(List<String> regionNames) {
 		for ( String regionName : regionNames ) {
 			allRegions.remove( regionName );

hibernate-infinispan/src/main/java/org/hibernate/cache/infinispan/util/CacheCommandInitializer.java

@@ -34,6 +34,12 @@ import org.infinispan.commands.module.ModuleCommandInitializer;
  */
 public class CacheCommandInitializer implements ModuleCommandInitializer {
 
+   /**
+    * Build an instance of {@link EvictAllCommand} for a given region.
+    *
+    * @param regionName name of region for {@link EvictAllCommand}
+    * @return a new instance of {@link EvictAllCommand}
+    */
 	public EvictAllCommand buildEvictAllCommand(String regionName) {
 		// No need to pass region factory because no information on that object
 		// is sent around the cluster. However, when the command factory builds

hibernate-infinispan/src/main/java/org/hibernate/cache/infinispan/util/Caches.java

@@ -42,6 +42,17 @@ public class Caches {
 		// Suppresses default constructor, ensuring non-instantiability.
 	}
 
+   /**
+    * Call an operation within a transaction. This method guarantees that the
+    * right pattern is used to make sure that the transaction is always either
+    * committed or rollback.
+    *
+    * @param cache instance whose transaction manager to use
+    * @param c callable instance to run within a transaction
+    * @param <T> type of callable return
+    * @return returns whatever the callable returns
+    * @throws Exception if any operation within the transaction fails
+    */
 	public static <T> T withinTx(
 			AdvancedCache cache,
 			Callable<T> c) throws Exception {
@@ -49,6 +60,17 @@ public class Caches {
 		return withinTx( cache.getTransactionManager(), c );
 	}
 
+   /**
+    * Call an operation within a transaction. This method guarantees that the
+    * right pattern is used to make sure that the transaction is always either
+    * committed or rollbacked.
+    *
+    * @param tm transaction manager
+    * @param c callable instance to run within a transaction
+    * @param <T> type of callable return
+    * @return returns whatever the callable returns
+    * @throws Exception if any operation within the transaction fails
+    */
 	public static <T> T withinTx(
 			TransactionManager tm,
 			Callable<T> c) throws Exception {
@@ -70,14 +92,36 @@ public class Caches {
 		}
 	}
 
+   /**
+    * Transform a given cache into a local cache
+    *
+    * @param cache to be transformed
+    * @return a cache that operates only in local-mode
+    */
 	public static AdvancedCache localCache(AdvancedCache cache) {
 		return cache.withFlags( Flag.CACHE_MODE_LOCAL );
 	}
 
+   /**
+    * Transform a given cache into a cache that ignores return values for
+    * operations returning previous values, i.e. {@link AdvancedCache#put(Object, Object)}
+    *
+    * @param cache to be transformed
+    * @return a cache that ignores return values
+    */
 	public static AdvancedCache ignoreReturnValuesCache(AdvancedCache cache) {
 		return cache.withFlags( Flag.SKIP_CACHE_LOAD, Flag.SKIP_REMOTE_LOOKUP );
 	}
 
+   /**
+    * Transform a given cache into a cache that ignores return values for
+    * operations returning previous values, i.e. {@link AdvancedCache#put(Object, Object)},
+    * adding an extra flag.
+    *
+    * @param cache to be transformed
+    * @param extraFlag to add to the returned cache
+    * @return a cache that ignores return values
+    */
 	public static AdvancedCache ignoreReturnValuesCache(
 			AdvancedCache cache, Flag extraFlag) {
 		return cache.withFlags(
@@ -85,6 +129,14 @@ public class Caches {
 		);
 	}
 
+   /**
+    * Transform a given cache into a cache that writes cache entries without
+    * waiting for them to complete, adding an extra flag.
+    *
+    * @param cache to be transformed
+    * @param extraFlag to add to the returned cache
+    * @return a cache that writes asynchronously
+    */
 	public static AdvancedCache asyncWriteCache(
 			AdvancedCache cache,
 			Flag extraFlag) {
@@ -96,6 +148,12 @@ public class Caches {
 		);
 	}
 
+   /**
+    * Transform a given cache into a cache that fails silently if cache writes fail.
+    *
+    * @param cache to be transformed
+    * @return a cache that fails silently if cache writes fail
+    */
 	public static AdvancedCache failSilentWriteCache(AdvancedCache cache) {
 		return cache.withFlags(
 				Flag.FAIL_SILENTLY,
@@ -105,6 +163,14 @@ public class Caches {
 		);
 	}
 
+   /**
+    * Transform a given cache into a cache that fails silently if
+    * cache writes fail, adding an extra flag.
+    *
+    * @param cache to be transformed
+    * @param extraFlag to be added to returned cache
+    * @return a cache that fails silently if cache writes fail
+    */
 	public static AdvancedCache failSilentWriteCache(
 			AdvancedCache cache,
 			Flag extraFlag) {
@@ -117,6 +183,13 @@ public class Caches {
 		);
 	}
 
+   /**
+    * Transform a given cache into a cache that fails silently if
+    * cache reads fail.
+    *
+    * @param cache to be transformed
+    * @return a cache that fails silently if cache reads fail
+    */
 	public static AdvancedCache failSilentReadCache(AdvancedCache cache) {
 		return cache.withFlags(
 				Flag.FAIL_SILENTLY,
@@ -124,6 +197,11 @@ public class Caches {
 		);
 	}
 
+   /**
+    * Broadcast an evict-all command with the given cache instance.
+    *
+    * @param cache instance used to broadcast command
+    */
 	public static void broadcastEvictAll(AdvancedCache cache) {
 		final RpcManager rpcManager = cache.getRpcManager();
 		if ( rpcManager != null ) {
@@ -137,16 +215,41 @@ public class Caches {
 		}
 	}
 
+   /**
+    * Indicates whether the given cache is configured with
+    * {@link org.infinispan.configuration.cache.CacheMode#INVALIDATION_ASYNC} or
+    * {@link org.infinispan.configuration.cache.CacheMode#INVALIDATION_SYNC}.
+    *
+    * @param cache to check for invalidation configuration
+    * @return true if the cache is configured with invalidation, false otherwise
+    */
 	public static boolean isInvalidationCache(AdvancedCache cache) {
 		return cache.getCacheConfiguration()
 				.clustering().cacheMode().isInvalidation();
 	}
 
+   /**
+    * Indicates whether the given cache is configured with
+    * {@link org.infinispan.configuration.cache.CacheMode#REPL_SYNC},
+    * {@link org.infinispan.configuration.cache.CacheMode#INVALIDATION_SYNC}, or
+    * {@link org.infinispan.configuration.cache.CacheMode#DIST_SYNC}.
+    *
+    * @param cache to check for synchronous configuration
+    * @return true if the cache is configured with synchronous mode, false otherwise
+    */
 	public static boolean isSynchronousCache(AdvancedCache cache) {
 		return cache.getCacheConfiguration()
 				.clustering().cacheMode().isSynchronous();
 	}
 
+   /**
+    * Indicates whether the given cache is configured to cluster its contents.
+    * A cache is considered to clustered if it's configured with any cache mode
+    * except {@link org.infinispan.configuration.cache.CacheMode#LOCAL}
+    *
+    * @param cache to check whether it clusters its contents
+    * @return true if the cache is configured with clustering, false otherwise
+    */
 	public static boolean isClustered(AdvancedCache cache) {
 		return cache.getCacheConfiguration()
 				.clustering().cacheMode().isClustered();

hibernate-infinispan/src/main/java/org/hibernate/cache/infinispan/util/EvictAllCommand.java

@@ -38,12 +38,23 @@ public class EvictAllCommand extends BaseRpcCommand {
 
 	private final BaseRegion region;
 
+   /**
+    * Evict all command constructor.
+    *
+    * @param regionName name of the region to evict
+    * @param region to evict
+    */
 	public EvictAllCommand(String regionName, BaseRegion region) {
 		// region name and cache names are the same...
 		super( regionName );
 		this.region = region;
 	}
 
+   /**
+    * Evict all command constructor.
+    *
+    * @param regionName name of the region to evict
+    */
 	public EvictAllCommand(String regionName) {
 		this( regionName, null );
 	}