lots of package-info.java files!

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

@@ -9,7 +9,8 @@
 import java.sql.SQLException;
 
 /**
- * Wraps a {@link SQLException}.  Indicates that an exception occurred during a JDBC call.
+ * Wraps a {@link SQLException} arising from the JDBC driver.
+ * Indicates that an error occurred during a JDBC call.
  *
  * @author Gavin King
  *

hibernate-core/src/main/java/org/hibernate/action/package-info.java

@@ -0,0 +1,18 @@
+/*
+ * Hibernate, Relational Persistence for Idiomatic Java
+ *
+ * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
+ * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
+ */
+
+/**
+ * This package defines the notion of an "action" which is scheduled for
+ * asynchronous execution by the event listeners. Every action implements
+ * {@link org.hibernate.action.spi.Executable}.
+ * <p>
+ * The {@link org.hibernate.engine.spi.ActionQueue} is responsible for
+ * scheduling and execution of the actions.
+ *
+ * @see org.hibernate.event
+ */
+package org.hibernate.action;

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

@@ -6,7 +6,8 @@
  */
 
 /**
- * Defines SPI hooks into the {@link org.hibernate.engine.spi.ActionQueue}.  Mainly for registering custom
- * {@link org.hibernate.action.spi.AfterTransactionCompletionProcess} and {@link org.hibernate.action.spi.BeforeTransactionCompletionProcess} hooks.
+ * Defines SPI hooks into the {@link org.hibernate.engine.spi.ActionQueue}, mainly for
+ * registering custom {@link org.hibernate.action.spi.AfterTransactionCompletionProcess}
+ * and {@link org.hibernate.action.spi.BeforeTransactionCompletionProcess} hooks.
  */
 package org.hibernate.action.spi;

hibernate-core/src/main/java/org/hibernate/annotations/package-info.java

@@ -10,7 +10,8 @@
  *
  * <h2 id="basic-value-mapping">Basic value mapping</h2>
  *
- * Hibernate supports 2 approaches to defining a mapping strategy for basic values:<ul>
+ * Hibernate supports two approaches to defining a mapping strategy for basic values:
+ * <ul>
  *     <li>
  *         A "compositional" approach using a combination of the following influencers for
  *         various parts of mapping<ul>
@@ -36,11 +37,10 @@
  *          custom-types as well.
  *     </li>
  * </ul>
- *
- * These 2 approaches are not intended to be mixed.  Specifying a custom-type takes precedence over
- * the compositional approach.  Though the compositional approach is recommended, both forms are
+ * These two approaches are not intended to be mixed. Specifying a custom-type takes precedence over
+ * the compositional approach. Although the compositional approach is recommended, both forms are
  * fully supported.
- *
+ * <p>
  * Please see the user guide for a more in-depth discussion.
  */
 package org.hibernate.annotations;

hibernate-core/src/main/java/org/hibernate/binder/package-info.java

@@ -0,0 +1,18 @@
+/*
+ * Hibernate, Relational Persistence for Idiomatic Java
+ *
+ * License: GNU Lesser General Public License (LGPL), version 2.1 or later
+ * See the lgpl.txt file in the root directory or http://www.gnu.org/licenses/lgpl-2.1.html
+ */
+
+/**
+ * 	This package defines an easy way to extend Hibernate with
+ * 	user-defined annotations that define customized O/R mappings
+ * 	of annotated entity attributes.
+ * 	<p>
+ *	The meta-annotation
+ *	{@link org.hibernate.annotations.AttributeBinderType}
+ * 	associates an {@link org.hibernate.binder.AttributeBinder}
+ * 	with a user-written annotation.
+ */
+package org.hibernate.binder;

hibernate-core/src/main/java/org/hibernate/boot/package-info.java

@@ -6,9 +6,11 @@
  */
 
 /**
- * This package contains the contracts that make up the Hibernate native
- * bootstrapping API (building a SessionFactory).
- *
- * See the <i>Native Bootstrapping</i> guide for details.
+ * This package contains the contracts that make up the bootstrap API
+ * for Hibernate. That is, they collectively provide a way to specify
+ * configuration information and construct a new instance of
+ * {@link org.hibernate.SessionFactory}.
+ * <p>
+ * See the <i>Native Bootstrapping</i> guide for more details.
  */
 package org.hibernate.boot;

hibernate-core/src/main/java/org/hibernate/boot/query/package-info.java

@@ -6,7 +6,7 @@
  */
 
 /**
- * Support for handling named-queries
+ * Support for handling named queries during the bootstrap process.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/boot/registry/package-info.java

@@ -8,16 +8,16 @@
 /**
  * Defines service registry contracts application are likely to want to utilize for
  * configuring Hibernate behavior.
- *
+ * <p>
  * Service registries are designed to be hierarchical.  This works in 2 fashions.  First registries can "hide" or
  * "override" services from parent registries.  It also allows granular building of registries as services
  * become available.
- *
+ * <p>
  * {@link org.hibernate.boot.registry.BootstrapServiceRegistry} is the base service registry, intended to be built via
  * {@link org.hibernate.boot.registry.BootstrapServiceRegistryBuilder} if you need customization.  For non-customized
  * {@link org.hibernate.boot.registry.BootstrapServiceRegistry} usage, the {@link org.hibernate.boot.registry.BootstrapServiceRegistryBuilder} and
  * {@link org.hibernate.boot.registry.BootstrapServiceRegistry} can be bypassed altogether.
- *
+ * <p>
  * Usually the next level in a standard registry set up is the {@link org.hibernate.boot.registry.StandardServiceRegistry}, intended to be built
  * by the {@link org.hibernate.boot.registry.StandardServiceRegistryBuilder} if you need customization.  The builder optionally takes the
  * {@link org.hibernate.boot.registry.BootstrapServiceRegistry} to use as a base; if none is provided a default one is generated assuming sensible

hibernate-core/src/main/java/org/hibernate/bytecode/BytecodeLogging.java

@@ -6,7 +6,6 @@
  */
 package org.hibernate.bytecode;
 
-import org.hibernate.boot.jaxb.JaxbLogger;
 import org.hibernate.internal.log.SubSystemLogging;
 
 import org.jboss.logging.Logger;

hibernate-core/src/main/java/org/hibernate/bytecode/package-info.java

@@ -0,0 +1,27 @@
+/*
+ * Hibernate, Relational Persistence for Idiomatic Java
+ *
+ * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
+ * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
+ */
+
+/**
+ *	This package defines an SPI for integrating bytecode libraries with Hibernate.
+ *	A bytecode library is used for:
+ * 	<ol>
+ * 		<li>
+ * 			<b>Reflection optimization</b> - to speed up the performance of entity
+ * 			and component construction and field/property access,
+ * 		</li>
+ * 		<li>
+ * 			<b>Proxy generation</b> - runtime building of proxies used to defer
+ * 			loading of lazy entities, and
+ * 		</li>
+ * 		<li>
+ * 			<b>Field-level interception</b> - build-time instrumentation of entity
+ * 			classes for the purpose of intercepting field-level access, for both
+ * 			lazy loading and dirty tracking.
+ * 		</li>
+ * 	</ol>
+ */
+package org.hibernate.bytecode;

hibernate-core/src/main/java/org/hibernate/cache/CacheException.java

@@ -9,7 +9,7 @@
 import org.hibernate.HibernateException;
 
 /**
- * Something went wrong in the cache
+ * Something went wrong in the cache.
  */
 public class CacheException extends HibernateException {
 	/**

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

@@ -6,6 +6,6 @@
  */
 
 /**
- * Package used to model various aspects of caching configuration
+ * Package used to model various aspects of caching configuration.
  */
 package org.hibernate.cache.cfg;

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

@@ -0,0 +1,14 @@
+/*
+ * Hibernate, Relational Persistence for Idiomatic Java
+ *
+ * License: GNU Lesser General Public License (LGPL), version 2.1 or later
+ * See the lgpl.txt file in the root directory or http://www.gnu.org/licenses/lgpl-2.1.html
+ */
+
+/**
+ * This package defines the API of the second-level cache service.
+ * <p>
+ * The subpackage {@link org.hibernate.cache.spi} defines an SPI
+ * used to integrate any third-party cache implementation.
+ */
+package org.hibernate.cache;

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

@@ -0,0 +1,42 @@
+/*
+ * Hibernate, Relational Persistence for Idiomatic Java
+ *
+ * License: GNU Lesser General Public License (LGPL), version 2.1 or later
+ * See the lgpl.txt file in the root directory or http://www.gnu.org/licenses/lgpl-2.1.html
+ */
+
+/**
+ * Defines contracts for transactional and concurrent access to cached
+ * {@linkplain org.hibernate.cache.spi.access.EntityDataAccess entity} and
+ * {@linkplain org.hibernate.cache.spi.access.CollectionDataAccess collection} data. Transactions pass in a
+ * timestamp indicating transaction start time which is then used to protect against concurrent access (exactly how
+ * that occurs is based on the actual access-strategy impl used). Two different implementation patterns are provided
+ * for:
+ * <ul>
+ * <li>
+ *     A transaction-aware cache implementation might be wrapped by a <i>synchronous</i> access strategy,
+ *     where updates to the cache are written to the cache inside the transaction.
+ * </li>
+ * <li>
+ *     A non-transaction-aware cache would be wrapped by an <i>asynchronous</i> access strategy, where items
+ *     are merely "soft locked" during the transaction and then updated during the "after transaction completion"
+ *     phase; the soft lock is not an actual lock on the database row - only upon the cached representation of the
+ *     item.
+ * </li>
+ * </ul>
+ * The <i>asynchronous</i> access strategies are: {@link org.hibernate.cache.spi.access.AccessType#READ_ONLY read-only},
+ * {@link org.hibernate.cache.spi.access.AccessType#READ_WRITE read-write} and
+ * {@link org.hibernate.cache.spi.access.AccessType#NONSTRICT_READ_WRITE nonstrict-read-write}.  The only
+ * <i>synchronous</i> access strategy is {@linkplain org.hibernate.cache.spi.access.AccessType#TRANSACTIONAL transactional}.
+ * <p>
+ * Note that, for an <i>asynchronous</i> cache, cache invalidation must be a two-step process (lock->unlock or
+ * lock->afterUpdate), since this is the only way to guarantee consistency with the database for a nontransactional
+ * cache implementation. For a <i>synchronous</i> cache, cache invalidation is a single step process (evict or update).
+ * Hence, these contracts ({@link org.hibernate.cache.spi.access.EntityDataAccess} and
+ * {@link org.hibernate.cache.spi.access.CollectionDataAccess}) define a three-step process to cater for both
+ * models (see the individual contracts for details).
+ * <p>
+ * Note that query result caching does not go through an access strategy; those caches are managed directly against
+ * the underlying {@link org.hibernate.cache.spi.QueryResultsRegion}.
+ */
+package org.hibernate.cache.spi.access;

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

@@ -0,0 +1,11 @@
+/*
+ * Hibernate, Relational Persistence for Idiomatic Java
+ *
+ * License: GNU Lesser General Public License (LGPL), version 2.1 or later
+ * See the lgpl.txt file in the root directory or http://www.gnu.org/licenses/lgpl-2.1.html
+ */
+
+/**
+ * This package defines formats for disassembled state kept in the second level cache.
+ */
+package org.hibernate.cache.spi.entry;