slight cleanup to the docs for o.h.cache.spi.support

hibernate-core/src/main/java/org/hibernate/boot/registry/selector/StrategyRegistration.java

@@ -7,8 +7,9 @@
 package org.hibernate.boot.registry.selector;
 
 /**
- * Describes the registration of a named strategy implementation.  A strategy + selector name should resolve
- * to a single implementation.
+ * Describes the registration of a named strategy implementation.
+ * <p>
+ * A strategy + selector name should resolve to a single implementation.
  *
  * @param <T> The type of the strategy described by this implementation registration.
  *
@@ -16,7 +17,7 @@ package org.hibernate.boot.registry.selector;
  */
 public interface StrategyRegistration<T> {
 	/**
-	 * The strategy role.  Best practice says this should be an interface.
+	 * The strategy role. Best practice says this should be an interface.
 	 *
 	 * @return The strategy contract/role.
 	 */

hibernate-core/src/main/java/org/hibernate/boot/registry/selector/StrategyRegistrationProvider.java

@@ -7,16 +7,18 @@
 package org.hibernate.boot.registry.selector;
 
 /**
- * Responsible for providing the registrations of strategy selector(s).  Can be registered directly with the
- * {@link org.hibernate.boot.registry.BootstrapServiceRegistry} or located via discovery.
+ * Responsible for providing the registrations of one or more strategy selectors.
+ * <p>
+ * Can be registered directly with the {@link org.hibernate.boot.registry.BootstrapServiceRegistry}
+ * or located via discovery.
  *
  * @author Steve Ebersole
  */
 public interface StrategyRegistrationProvider {
 	/**
-	 * Get all StrategyRegistrations announced by this provider.
+	 * Get all {@link StrategyRegistration}s announced by this provider.
 	 *
-	 * @return All StrategyRegistrations
+	 * @return All {@link StrategyRegistration}s
 	 */
 	Iterable<StrategyRegistration> getStrategyRegistrations();
 }

hibernate-core/src/main/java/org/hibernate/cache/spi/support/DomainDataStorageAccess.java

@@ -9,7 +9,7 @@ package org.hibernate.cache.spi.support;
 import org.hibernate.engine.spi.SharedSessionContractImplementor;
 
 /**
- * Specialization of {@link StorageAccess} for domain data regions
+ * Specialization of {@link StorageAccess} for domain data regions.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/cache/spi/support/StorageAccess.java

@@ -9,11 +9,11 @@ package org.hibernate.cache.spi.support;
 import org.hibernate.engine.spi.SharedSessionContractImplementor;
 
 /**
- * A general read/write abstraction over the specific "cache"
- * object from the caching provider.
+ * A general read/write abstraction over the specific "cache" object from the caching provider.
  *
  * @apiNote Similar to {@link org.hibernate.cache.spi.access.CachedDomainDataAccess},
- * some methods represent "transactional" (access to Session) and some are non-"transactional"
+ *          some methods handle "transactional" access (access in the scope of a session),
+ *          and some are non-"transactional" (for cache management outside a session).
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/cache/spi/support/package-info.java

@@ -6,31 +6,25 @@
  */
 
 /**
- * Package intended for simplifying the worked needed to implement a caching provider.
- * Centers around the concept of {@link org.hibernate.cache.spi.support.StorageAccess}
- * and {@link org.hibernate.cache.spi.support.DomainDataStorageAccess} to implement
- * most of the "grunt work" associated with the implementation.
+ * This package provides a framework intended to reduce the work needed to implement
+ * a caching provider. It takes care of most of the "grunt work" associated with the
+ * implementation, leaving the integrator to implement the interfaces
+ * {@link org.hibernate.cache.spi.support.StorageAccess} and
+ * {@link org.hibernate.cache.spi.support.DomainDataStorageAccess}.
  * <p>
- * A typical integration would just implement:
+ * A typical integration would provide:
  * <ol>
- * <li>a custom {@code StorageAccess}/{@code DomainDataStorageAccess}, along with
- * <li>a custom {@link org.hibernate.cache.spi.support.RegionFactoryTemplate}, in
- *     particular:
- *     <ul>
- *     <li>{@link org.hibernate.cache.spi.support.RegionFactoryTemplate#createDomainDataStorageAccess}
- *     <li>{@link org.hibernate.cache.spi.support.RegionFactoryTemplate#createQueryResultsRegionStorageAccess}
- *     <li>{@link org.hibernate.cache.spi.support.RegionFactoryTemplate#createTimestampsRegionStorageAccess}
- *     </ul>
+ * <li>a custom {@code StorageAccess} or {@code DomainDataStorageAccess}, along with
+ * <li>a custom {@link org.hibernate.cache.spi.support.RegionFactoryTemplate}.
  * </ol>
  * <p>
- * Voila! Functioning cache provider.
- * <p>
- * The preferred approach to "provide an integration" is through a custom
+ * The preferred way to register these implementations to Hibernate is via a custom
  * {@link org.hibernate.boot.registry.selector.StrategyRegistrationProvider}.
  * <p>
- * Both {@code hibernate-testing} ({@code org.hibernate.testing.cache.CachingRegionFactory})
- * and {@code hibernate-jcache} ({@code org.hibernate.cache.jcache.internal.JCacheRegionFactory})
- * provide examples of using this support package to implement a caching
- * provider.
+ * Examples of using this support package to implement a caching provider include:
+ * <ul>
+ * <li>{@code org.hibernate.testing.cache.CachingRegionFactory} in {@code hibernate-testing}, and
+ * <li>{@code org.hibernate.cache.jcache.internal.JCacheRegionFactory} in {@code hibernate-jcache}.
+ * </ul>
  */
 package org.hibernate.cache.spi.support;