further work on the API documentation

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

@@ -6,6 +6,9 @@
  */
 
 /**
- * Internals for action processing.
+ * The various concrete action implementations.
+ * <p>
+ * These actions are scheduled for execution by the concrete event
+ * listeners defined in {@link org.hibernate.event.internal}.
  */
 package org.hibernate.action.internal;

hibernate-core/src/main/java/org/hibernate/action/spi/Executable.java

@@ -12,8 +12,9 @@
 import org.hibernate.event.spi.EventSource;
 
 /**
- * An operation which may be scheduled for later execution.  Usually, the operation is a database
+ * An operation which may be scheduled for later execution. Usually, the
- * insert/update/delete, together with required second-level cache management.
+ * operation is a database insert/update/delete, together with required
+ * second-level cache management.
  * 
  * @author Gavin King
  * @author Steve Ebersole

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

@@ -6,8 +6,17 @@
  */
 
 /**
- * Defines SPI hooks into the {@link org.hibernate.engine.spi.ActionQueue}, mainly for
+ * This SPI package defines an abstraction over the notion of an "action"
- * registering custom {@link org.hibernate.action.spi.AfterTransactionCompletionProcess}
+ * which is scheduled for asynchronous execution by the event listeners.
- * and {@link org.hibernate.action.spi.BeforeTransactionCompletionProcess} hooks.
+ * 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.
+ * <p>
+ * This package also defines the SPI callback interfaces for the
+ * {@link org.hibernate.engine.spi.ActionQueue}, allowing registration of
+ * custom {@link org.hibernate.action.spi.AfterTransactionCompletionProcess}
+ * and {@link org.hibernate.action.spi.BeforeTransactionCompletionProcess}
+ * processors.
  */
 package org.hibernate.action.spi;

hibernate-core/src/main/java/org/hibernate/binder/internal/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
+ */
+
+/**
+ * 	Built-in implementations of {@link org.hibernate.binder.AttributeBinder}.
+ */
+package org.hibernate.binder.internal;

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

@@ -6,6 +6,6 @@
  */
 
 /**
- * The internals of archive scanning support
+ * The internals of archive scanning support.
  */
 package org.hibernate.boot.archive.internal;

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

@@ -0,0 +1,13 @@
+/*
+ * 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.
+ */
+
+/**
+ * Implementation of the service for processing and handling {@code cfg.xml} files.
+ *
+ * @author Steve Ebersole
+ */
+package org.hibernate.boot.cfgxml.internal;

hibernate-core/src/main/java/org/hibernate/boot/cfgxml/spi/LoadedConfig.java

@@ -30,8 +30,8 @@
 /**
  * Models the information gleaned from parsing a {@code cfg.xml} file.
  * <p>
- * A LoadedConfig is built via {@link #consume}.  An aggregated representation
+ * A {@link LoadedConfig} is built via {@link #consume}. An aggregated
- * can be maintained through calls to {@link #merge}
+ * representation can be maintained through calls to {@link #merge}.
  */
 public class LoadedConfig {
 	private static final Logger log = Logger.getLogger( LoadedConfig.class );

hibernate-core/src/main/java/org/hibernate/boot/cfgxml/spi/MappingReference.java

@@ -14,7 +14,7 @@
 import org.hibernate.internal.util.config.ConfigurationException;
 
 /**
- * Represents a {@code <mapping/>} element within a cfg.xml file.
+ * Represents a {@code <mapping/>} element within a {@code cfg.xml} file.
  *
  * @author Steve Ebersole
  */

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

@@ -0,0 +1,15 @@
+/*
+ * 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.
+ */
+
+/**
+ * An SPI service for processing and handling {@code cfg.xml} files.
+ *
+ * @see org.hibernate.boot.cfgxml.spi.LoadedConfig
+ *
+ * @author Steve Ebersole
+ */
+package org.hibernate.boot.cfgxml.spi;

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

@@ -6,33 +6,11 @@
  */
 package org.hibernate.boot.registry.selector.spi;
 
-import java.util.Collection;
-import java.util.concurrent.Callable;
-
 import org.hibernate.boot.registry.selector.internal.LazyServiceResolver;
 import org.hibernate.dialect.Dialect;
 import org.hibernate.service.Service;
 
 /**
- * Service which acts as a registry for named strategy implementations.
- * <p>
- * Strategies are more open ended than services, though a strategy managed here might very well also be a service.  The
- * strategy is any interface that has multiple, (possibly short) named implementations.
- * <p>
- * StrategySelector manages resolution of particular implementation by (possibly short) name via the
- * {@link StrategySelector#selectStrategyImplementor} method, which is the main contract here.  As indicated in the docs of that
- * method the given name might be either a short registered name or the implementation FQN.  As an example, consider
- * resolving the {@link org.hibernate.resource.transaction.spi.TransactionCoordinatorBuilder} implementation to use.  To use the
- * JDBC-based TransactionCoordinatorBuilder the passed name might be either {@code "jdbc"} or
- * {@code "org.hibernate.resource.transaction.backend.jdbc.internal.JdbcResourceLocalTransactionCoordinatorBuilderImpl"} (which is the FQN).
- * <p>
- * Strategy implementations can be managed by {@link StrategySelector#registerStrategyImplementor} and
- * {@link StrategySelector#unRegisterStrategyImplementor}.  Originally designed to help the OSGi use case, though no longer used there.
- * <p>
- * The service also exposes a general typing API via {@link StrategySelector#resolveStrategy} and {@link StrategySelector#resolveDefaultableStrategy}
- * which accept implementation references rather than implementation names, allowing for a multitude of interpretations
- * of said "implementation reference".  See the docs for {@link StrategySelector#resolveDefaultableStrategy} for details.
- *
  * @author Christian Beikov
  */
 public interface DialectSelector extends Service, LazyServiceResolver<Dialect> {

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

@@ -14,18 +14,18 @@
 /**
  * Service which acts as a registry for named strategy implementations.
  * <p>
- * Strategies are more open ended than services, though a strategy managed here might very well also be a service.  The
+ * Strategies are more open-ended than services, though a strategy managed here might very well also be a service.
- * strategy is any interface that has multiple, (possibly short) named implementations.
+ * The strategy is any interface that has multiple, (possibly short) named implementations.
  * <p>
- * StrategySelector manages resolution of particular implementation by (possibly short) name via the
+ * {@code StrategySelector} manages resolution of particular implementation by (possibly short) name via the
  * {@link #selectStrategyImplementor} method, which is the main contract here.  As indicated in the docs of that
  * method the given name might be either a short registered name or the implementation FQN.  As an example, consider
- * resolving the {@link org.hibernate.resource.transaction.spi.TransactionCoordinatorBuilder} implementation to use.  To use the
+ * resolving the {@link org.hibernate.resource.transaction.spi.TransactionCoordinatorBuilder} implementation to use.
- * JDBC-based TransactionCoordinatorBuilder the passed name might be either {@code "jdbc"} or
+ * To use the JDBC-based {@code TransactionCoordinatorBuilder} the passed name might be either {@code "jdbc"} or
- * {@code "org.hibernate.resource.transaction.backend.jdbc.internal.JdbcResourceLocalTransactionCoordinatorBuilderImpl"} (which is the FQN).
+ * {@code "org.hibernate.resource.transaction.backend.jdbc.internal.JdbcResourceLocalTransactionCoordinatorBuilderImpl"}.
  * <p>
- * Strategy implementations can be managed by {@link #registerStrategyImplementor} and
+ * Strategy implementations can be managed by {@link #registerStrategyImplementor} and {@link #unRegisterStrategyImplementor}.
- * {@link #unRegisterStrategyImplementor}.  Originally designed to help the OSGi use case, though no longer used there.
+ * Originally designed to help the OSGi use case, though no longer used there.
  * <p>
  * The service also exposes a general typing API via {@link #resolveStrategy} and {@link #resolveDefaultableStrategy}
  * which accept implementation references rather than implementation names, allowing for a multitude of interpretations

hibernate-core/src/main/java/org/hibernate/cache/cfg/internal/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
+ */
+
+/**
+ * Implementation of the second-level cache configuration SPI.
+ */
+package org.hibernate.cache.cfg.internal;

hibernate-core/src/main/java/org/hibernate/engine/config/internal/ConfigurationServiceImpl.java

@@ -19,7 +19,7 @@
 import org.jboss.logging.Logger;
 
 /**
- * The standard ConfigurationService implementation
+ * The standard {@link ConfigurationService} implementation.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/engine/config/internal/ConfigurationServiceInitiator.java

@@ -13,7 +13,7 @@
 import org.hibernate.service.spi.ServiceRegistryImplementor;
 
 /**
- * The ServiceInitiator for the ConfigurationService
+ * The {@link org.hibernate.service.spi.ServiceInitiator} for the {@link ConfigurationService}.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/engine/config/internal/package-info.java

@@ -6,6 +6,6 @@
  */
 
 /**
- * Internal support for the configuration service implementation
+ * The built-in implementation of the configuration service.
  */
 package org.hibernate.engine.config.internal;

hibernate-core/src/main/java/org/hibernate/engine/config/package-info.java

@@ -6,7 +6,7 @@
  */
 
 /**
- * Package for the configuration service, which provides access to configuration settings as part of a
+ * Contains the configuration service, which provides access to
- * ServiceRegistry
+ * settings via a {@link org.hibernate.service.ServiceRegistry}.
  */
 package org.hibernate.engine.config;

hibernate-core/src/main/java/org/hibernate/engine/config/spi/StandardConverters.java

@@ -10,7 +10,7 @@
 import static org.hibernate.engine.config.spi.ConfigurationService.Converter;
 
 /**
- * Standard set of setting converters
+ * Standard set of setting converters.
  *
  * @author Steve Ebersole
  */

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

@@ -6,6 +6,8 @@
  */
 
 /**
- * SPI Package for the configuration service.
+ * Defines the SPI of the configuration service.
+ * <p>
+ * Provides access to settings via a {@link org.hibernate.service.ServiceRegistry}.
  */
 package org.hibernate.engine.config.spi;

hibernate-core/src/main/java/org/hibernate/engine/internal/package-info.java

@@ -7,7 +7,7 @@
 
 /**
  * Support for many of the internal workings of Hibernate.
- *
+ * <p>
  * See also the {@link org.hibernate.internal} package.
  */
 package org.hibernate.engine.internal;

hibernate-core/src/main/java/org/hibernate/engine/transaction/jta/platform/internal/package-info.java

@@ -0,0 +1,12 @@
+/*
+ * 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>.
+ */
+
+/**
+ * A range of container-specific implementations of
+ * {@link org.hibernate.engine.transaction.jta.platform.spi.JtaPlatform}.
+ */
+package org.hibernate.engine.transaction.jta.platform.internal;

hibernate-core/src/main/java/org/hibernate/event/service/internal/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>.
+ */
+
+/**
+ * Implementation of the event listener registration service.
+ */
+package org.hibernate.event.service.internal;

hibernate-core/src/main/java/org/hibernate/event/service/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>.
+ */
+
+/**
+ * Support for the event listener registration service.
+ */
+package org.hibernate.event.service;

hibernate-core/src/main/java/org/hibernate/event/service/spi/EventListenerRegistry.java

@@ -11,8 +11,9 @@
 import org.hibernate.service.Service;
 
 /**
- * Service for accessing each {@link EventListenerGroup} by {@link EventType}, as well as convenience
+ * Service for accessing each {@link EventListenerGroup} by {@link EventType},
- * methods for managing the listeners registered in each {@link EventListenerGroup}.
+ * along with  convenience methods for managing the listeners registered in
+ * each {@link EventListenerGroup}.
  *
  * @author Steve Ebersole
  */

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

@@ -0,0 +1,13 @@
+/*
+ * 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>.
+ */
+
+/**
+ * An SPI for the event listener registration service.
+ *
+ * @see org.hibernate.event.service.spi.EventListenerRegistry
+ */
+package org.hibernate.event.service.spi;

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

@@ -6,7 +6,7 @@
  */
 
 /**
- * Implements and extends the JPA-defined {@link jakarta.persistence.EntityGraph entity graph} API.
+ * Implements and extends the JPA-defined {@linkplain jakarta.persistence.EntityGraph entity graph} API.
  *
  * @apiNote This entire package (including sub-packages) is considered incubating
  */

hibernate-core/src/main/java/org/hibernate/id/factory/internal/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
+ */
+
+/**
+ * Implementation of the SPI for id generator factories.
+ */
+package org.hibernate.id.factory.internal;

hibernate-core/src/main/java/org/hibernate/id/factory/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
+ */
+
+/**
+ * Defines a {@linkplain org.hibernate.service.Service service} for creating
+ * id generators.
+ * <p>
+ * This is an older mechanism for instantiating and configuring id generators
+ * which predates the existence of {@link org.hibernate.generator.Generator}.
+ * It is used when id generators are identified by stringly-typed names.
+ *
+ * @see org.hibernate.id.factory.IdentifierGeneratorFactory
+ */
+package org.hibernate.id.factory;

hibernate-core/src/main/java/org/hibernate/id/factory/spi/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
+ */
+
+/**
+ * Contains an SPI for id generator factories.
+ */
+package org.hibernate.id.factory.spi;

hibernate-core/src/main/java/org/hibernate/id/insert/package-info.java

@@ -0,0 +1,13 @@
+/*
+ * 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
+ */
+
+/**
+ * Contains a framework of strategies for retrieving database-generated ids.
+ *
+ * @see org.hibernate.id.insert.InsertGeneratedIdentifierDelegate
+ */
+package org.hibernate.id.insert;

hibernate-core/src/main/java/org/hibernate/id/uuid/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
+ */
+
+/**
+ * Contains the {@link org.hibernate.id.uuid.UuidGenerator}.
+ */
+package org.hibernate.id.uuid;

hibernate-core/src/main/java/org/hibernate/integrator/internal/package-info.java

@@ -0,0 +1,12 @@
+/*
+ * 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
+ */
+
+/**
+ * Implementation of the SPI for extensions which integrate with Hibernate via the
+ * {@link org.hibernate.service.Service} mechanism.
+ */
+package org.hibernate.integrator.internal;

hibernate-core/src/main/java/org/hibernate/metamodel/model/convert/internal/package-info.java

@@ -0,0 +1,13 @@
+/*
+ * 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
+ */
+
+/**
+ * Implements the SPI for basic-value conversions.
+ *
+ * @see org.hibernate.metamodel.model.convert.spi.BasicValueConverter
+ */
+package org.hibernate.metamodel.model.convert.internal;

hibernate-core/src/main/java/org/hibernate/metamodel/model/convert/package-info.java

@@ -6,11 +6,15 @@
  */
 
 /**
- * Support for basic-value conversions.  The main contract is
+ * Support for basic-value conversions. The main contract is
  * {@link org.hibernate.metamodel.model.convert.spi.BasicValueConverter}.
- *
+ * <p>
  * All basic value conversions are defined by this package including:
- * 		* Enum conversions - {@link org.hibernate.metamodel.model.convert.spi.EnumValueConverter}
+ * <ul>
- * 		* AttributeConverter - {@link org.hibernate.metamodel.model.convert.spi.JpaAttributeConverter}
+ * <li>Java {@code enum} conversions via
+ *     {@link org.hibernate.metamodel.model.convert.spi.EnumValueConverter}
+ * <li>support for {@link jakarta.persistence.AttributeConverter} via
+ *     {@link org.hibernate.metamodel.model.convert.spi.JpaAttributeConverter}
+ * </ul>
  */
 package org.hibernate.metamodel.model.convert;

hibernate-core/src/main/java/org/hibernate/metamodel/model/convert/spi/BasicValueConverter.java

@@ -13,13 +13,12 @@
 
 /**
  * Support for basic-value conversions.
- *
+ * <p>
- * Conversions might be defined by:
+ * Conversions might be determined by:
- *
+ * <ul>
- * 		* a custom JPA {@link jakarta.persistence.AttributeConverter},
+ * <li>a custom JPA {@link jakarta.persistence.AttributeConverter}, or
- * 		* implicitly, based on the Java type (e.g., enums)
+ * <li>implicitly, based on the Java type, for example, for Java {@code enum}s.
- * 	    * etc
+ * </ul>
- *
  * @param <D> The Java type we can use to represent the domain (object) type
  * @param <R> The Java type we can use to represent the relational type
  *

hibernate-core/src/main/java/org/hibernate/metamodel/model/convert/spi/EnumValueConverter.java

@@ -20,7 +20,7 @@
 import static org.hibernate.metamodel.model.convert.internal.EnumHelper.getEnumeratedValues;
 
 /**
- * BasicValueConverter extension for enum-specific support
+ * {@link BasicValueConverter} extension for enum-specific support
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/metamodel/model/convert/spi/JpaAttributeConverter.java

@@ -12,7 +12,7 @@
 import org.hibernate.type.descriptor.java.JavaType;
 
 /**
- * BasicValueConverter extension for AttributeConverter-specific support
+ * {@link BasicValueConverter} extension for {@link AttributeConverter}-specific support
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/metamodel/model/convert/spi/package-info.java

@@ -0,0 +1,13 @@
+/*
+ * 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
+ */
+
+/**
+ * An SPI for basic-value conversions.
+ *
+ * @see org.hibernate.metamodel.model.convert.spi.BasicValueConverter
+ */
+package org.hibernate.metamodel.model.convert.spi;

hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/internal/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
+ */
+
+/**
+ * Implementation of the SPI for the runtime domain metamodel.
+ */
+package org.hibernate.metamodel.model.domain.internal;

hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/spi/package-info.java

@@ -0,0 +1,13 @@
+/*
+ * 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
+ */
+
+/**
+ * An SPI for the runtime domain metamodel.
+ *
+ * @see org.hibernate.metamodel.model.domain.spi.JpaMetamodelImplementor
+ */
+package org.hibernate.metamodel.model.domain.spi;

hibernate-core/src/main/java/org/hibernate/persister/collection/mutation/package-info.java

@@ -8,12 +8,12 @@
 /**
  * Defines support for performing mutation operations against collections.
  *
- * @apiNote The names used here are logical.  E.g. "inserting a row" may actually
+ * @apiNote The names used here are logical. E.g. "inserting a row" may actually
- * execute an UPDATE statement instead of an INSERT.  This is generally
+ *          execute an UPDATE statement instead of an INSERT. This is generally
- * delineated based on whether there is a collection table involved or
+ *          delineated based on whether there is a collection table involved or
- * not.  In standard Hibernate terms, this breaks down to the distinction
+ *          not. In terms of our usual model, this breaks down to the distinction
- * between {@link org.hibernate.persister.collection.BasicCollectionPersister}
+ *          between {@link org.hibernate.persister.collection.BasicCollectionPersister}
- * and {@link org.hibernate.persister.collection.OneToManyPersister}.
+ *          and {@link org.hibernate.persister.collection.OneToManyPersister}.
  */
 @Incubating
 package org.hibernate.persister.collection.mutation;

hibernate-core/src/main/java/org/hibernate/persister/internal/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
+ */
+
+/**
+ * Built-in implementation of the SPI for integrating entity and collection persisters.
+ */
+package org.hibernate.persister.internal;

hibernate-core/src/main/java/org/hibernate/property/access/internal/package-info.java

@@ -0,0 +1,12 @@
+/*
+ * 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>.
+ */
+
+/**
+ * Contains various implementations of
+ * {@link org.hibernate.property.access.spi.PropertyAccessStrategy}.
+ */
+package org.hibernate.property.access.internal;

hibernate-core/src/main/java/org/hibernate/property/access/spi/Getter.java

@@ -15,7 +15,7 @@
 import org.hibernate.engine.spi.SharedSessionContractImplementor;
 
 /**
- * The contract for getting value for a persistent property from its container/owner
+ * The contract for getting the value of a persistent attribute from its container/owner.
  *
  * @author Gavin King
  * @author Steve Ebersole

hibernate-core/src/main/java/org/hibernate/property/access/spi/PropertyAccess.java

@@ -9,10 +9,10 @@
 import org.hibernate.metamodel.spi.ManagedTypeRepresentationStrategy;
 
 /**
- * Describes access to a particular persistent property in terms of getting and setting
+ * Defines how a given persistent attribute is accessed by exposing
- * values.
+ * a {@link Getter} and a {@link Setter} for the attribute.
  * <p>
- * Instances are obtained from {@link PropertyAccessStrategy}
+ * Instances are obtained from a {@link PropertyAccessStrategy}.
  *
  * @see ManagedTypeRepresentationStrategy
  *
@@ -21,21 +21,21 @@
  */
 public interface PropertyAccess {
 	/**
-	 * Access to the PropertyAccessStrategy that created this PropertyAccess
+	 * Access to the {@link PropertyAccessStrategy} that created this instance.
 	 *
-	 * @return The PropertyAccessStrategy that created this PropertyAccess
+	 * @return The {@code PropertyAccessStrategy}
 	 */
 	PropertyAccessStrategy getPropertyAccessStrategy();
 
 	/**
-	 * Obtain the delegate for getting values for the described persistent property
+	 * Obtain the delegate for getting values of the persistent attribute.
 	 *
 	 * @return The property getter
 	 */
 	Getter getGetter();
 
 	/**
-	 * Obtain the delegate for setting values for the described persistent property
+	 * Obtain the delegate for setting values of the persistent attribute.
 	 *
 	 * @return The property setter
 	 */

hibernate-core/src/main/java/org/hibernate/property/access/spi/PropertyAccessBuildingException.java

@@ -9,7 +9,7 @@
 import org.hibernate.HibernateException;
 
 /**
- * Indicates a problem while building a PropertyAccess
+ * Indicates a problem while building a {@link PropertyAccess}.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/property/access/spi/PropertyAccessStrategy.java

@@ -7,13 +7,14 @@
 package org.hibernate.property.access.spi;
 
 /**
- * Describes a strategy for persistent property access (field, JavaBean-style property, etc).
+ * Describes a strategy for accessing a persistent attribute,
- *
+ * for example: field, JavaBean-style property, or whatever.
+ * <p>
  * Acts as a factory for {@link PropertyAccess} instances.
  */
 public interface PropertyAccessStrategy {
 	/**
-	 * Build a PropertyAccess for the indicated property
+	 * Build a {@link PropertyAccess} for the indicated property
 	 *
 	 * @param containerJavaType The Java type that contains the property; may be {@code null} for non-pojo cases.
 	 * @param propertyName The property name

hibernate-core/src/main/java/org/hibernate/property/access/spi/PropertyAccessStrategyResolver.java

@@ -10,12 +10,12 @@
 import org.hibernate.service.Service;
 
 /**
- * Contract for resolving the PropertyAccessStrategy to use.
+ * Contract for resolving the {@link PropertyAccessStrategy} to use.
- * <p>
- * todo : moving forward I'd prefer this not be a service, but instead a strategy on the MetadataBuildingContext or MetadataBuildingOptions
  *
  * @author Steve Ebersole
  */
+//TODO: moving forward I'd prefer this not be a service, but instead a
+//      strategy on the MetadataBuildingContext or MetadataBuildingOptions
 public interface PropertyAccessStrategyResolver extends Service {
 	/**
 	 * Resolve the PropertyAccessStrategy to use

hibernate-core/src/main/java/org/hibernate/property/access/spi/Setter.java

@@ -10,7 +10,7 @@
 import java.lang.reflect.Method;
 
 /**
- * The contract for setting a persistent property value into its container/owner
+ * The contract for setting the value of a persistent attribute on its container/owner.
  *
  * @author Gavin King
  * @author Steve Ebersole

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

@@ -6,6 +6,9 @@
  */
 
 /**
- * Integration contracts related with {@link org.hibernate.property.access.spi.PropertyAccessStrategy}
+ * An SPI abstracting how persistent attributes of an entity or embeddable type
+ * are accessed by Hibernate.
+ *
+ * @see org.hibernate.property.access.spi.PropertyAccessStrategy
  */
 package org.hibernate.property.access.spi;

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

@@ -6,10 +6,8 @@
  */
 
 /**
- * Hibernate's support for JPA criteria queries.
+ * Support for JPA criteria queries.
- * <p>
+ *
- * Note JPA criteria are similar to Hibernate's legacy notion
+ * @see org.hibernate.query.criteria.HibernateCriteriaBuilder
- * of a detached criteria.  Ultimately the criteria tree is transformed
- * into an SQM form and becomes a Query.
  */
 package org.hibernate.query.criteria;

hibernate-core/src/main/java/org/hibernate/query/criteria/spi/CriteriaBuilderExtension.java

@@ -10,8 +10,8 @@
 import org.hibernate.service.Service;
 
 /**
- * Interface which allows to extend {@link HibernateCriteriaBuilder}
+ * Interface which allows extension of {@link HibernateCriteriaBuilder}
- * with additional functionality by registering a {@link Service}
+ * with additional functionality by registering a {@link Service}.
  *
  * @author Marco Belladelli
  */

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

@@ -0,0 +1,12 @@
+/*
+ * 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
+ */
+
+/**
+ * SPI for extending {@link org.hibernate.query.criteria.HibernateCriteriaBuilder}
+ * with additional functionality by registering a {@link org.hibernate.service.Service}.
+ */
+package org.hibernate.query.criteria.spi;

hibernate-core/src/main/java/org/hibernate/resource/beans/container/internal/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
+ */
+
+/**
+ * An implementation of the bean container SPI based on CDI.
+ */
+package org.hibernate.resource.beans.container.internal;

hibernate-core/src/main/java/org/hibernate/resource/beans/container/package-info.java

@@ -6,6 +6,7 @@
  */
 
 /**
- * Package for integrating dependency-injection bean containers
+ * This package provides support for integrating bean containers like CDI.
+ * A "bean container" is usually based around dependency injection.
  */
 package org.hibernate.resource.beans.container;

hibernate-core/src/main/java/org/hibernate/resource/beans/container/spi/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
+ */
+
+/**
+ * An SPI abstracting over CDI-like bean containers.
+ */
+package org.hibernate.resource.beans.container.spi;

hibernate-core/src/main/java/org/hibernate/resource/beans/internal/ManagedBeanRegistryImpl.java

@@ -18,7 +18,7 @@
 import org.hibernate.service.spi.Stoppable;
 
 /**
- * Abstract support (template pattern) for ManagedBeanRegistry implementations
+ * Abstract support (template pattern) for {@link ManagedBeanRegistry} implementations
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/resource/beans/package-info.java

@@ -6,9 +6,9 @@
  */
 
 /**
- * Defines Hibernate's integration with CDI.  Because CDI may or may not be available
+ * Defines Hibernate's integration with CDI. Because CDI may or may not be available
- * a lot of this support is directed toward abstracting/encapsulating CDI.  The
+ * a lot of this support is directed toward abstracting/encapsulating CDI. The central
- * central contracts here from a consumption point-of-view are
+ * contracts here from a client point of view are
  * {@link org.hibernate.resource.beans.spi.ManagedBean} and
  * {@link org.hibernate.resource.beans.spi.ManagedBeanRegistry} which may or may not
  * really be backed by CDI.

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

@@ -0,0 +1,19 @@
+/*
+ * 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 an SPI for integration with CDI-like containers.
+ * <p>
+ * Because CDI may or may not be available, much of this support
+ * is directed toward abstracting/encapsulating CDI.
+ * <p>
+ * The central contracts here from a client point of view are
+ * {@link org.hibernate.resource.beans.spi.ManagedBean} and
+ * {@link org.hibernate.resource.beans.spi.ManagedBeanRegistry},
+ * which may or may not really be backed by CDI.
+ */
+package org.hibernate.resource.beans.spi;

hibernate-core/src/main/java/org/hibernate/resource/jdbc/internal/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
+ */
+
+/**
+ * Implementation of the SPI for managing JDBC connections and other heavyweight resources.
+ */
+package org.hibernate.resource.jdbc.internal;

hibernate-core/src/main/java/org/hibernate/resource/jdbc/package-info.java

@@ -7,5 +7,8 @@
 
 /**
  * A facility for managing JDBC connections and other heavyweight resources.
+ *
+ * @see org.hibernate.resource.jdbc.LogicalConnection
+ * @see org.hibernate.resource.jdbc.ResourceRegistry
  */
 package org.hibernate.resource.jdbc;

hibernate-core/src/main/java/org/hibernate/resource/jdbc/spi/JdbcSessionContext.java

@@ -10,7 +10,7 @@
 import org.hibernate.service.ServiceRegistry;
 
 /**
- * Provides the JdbcSession implementation with contextual information it needs during its lifecycle.
+ * Provides the {@code JdbcSession} with contextual information it needs during its lifecycle.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/resource/jdbc/spi/JdbcSessionOwner.java

@@ -10,12 +10,14 @@
 import org.hibernate.resource.transaction.spi.TransactionCoordinator;
 
 /**
- * Contract for something that controls a JdbcSessionContext.  The name comes from the
+ * Contract for something that controls a {@link JdbcSessionContext}.
- * design idea of a JdbcSession which encapsulates this information, which we will hopefully
+ * <p>
- * get back to later.
+ * The term "JDBC session" is taken from the SQL specification which
+ * calls a connection and its associated transaction context a "session".
  *
- * The term "JDBC session" is taken from the SQL specification which calls a connection
+ * @apiNote The name comes from the design idea of a {@code JdbcSession}
- * and its associated transaction context a "session".
+ *           which encapsulates this information, which we will hopefully
+ *           get back to later.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/resource/jdbc/spi/LogicalConnectionImplementor.java

@@ -13,7 +13,7 @@
 import org.hibernate.resource.jdbc.LogicalConnection;
 
 /**
- * SPI contract for LogicalConnection
+ * SPI contract for {@link LogicalConnection}.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/resource/jdbc/spi/PhysicalJdbcTransaction.java

@@ -9,7 +9,7 @@
 import org.hibernate.resource.transaction.backend.jdbc.spi.JdbcResourceTransaction;
 
 /**
- * Provides access to manage "transactionality" via the JDBC Connection
+ * Provides access to manage "transactionality" via the JDBC {@link java.sql.Connection}.
  *
  * @author Steve Ebersole
  */

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

@@ -0,0 +1,12 @@
+/*
+ * 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
+ */
+
+/**
+ * An SPI for managing JDBC connections and other heavyweight resources,
+ * based around the idea of a "JDBC session".
+ */
+package org.hibernate.resource.jdbc.spi;

hibernate-core/src/main/java/org/hibernate/resource/transaction/backend/jdbc/internal/JdbcResourceLocalTransactionCoordinatorBuilderImpl.java

@@ -16,7 +16,7 @@
 import org.hibernate.tool.schema.internal.exec.JdbcContext;
 
 /**
- * Concrete builder for resource-local TransactionCoordinator instances.
+ * Concrete builder for resource-local {@link TransactionCoordinator} instances.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/resource/transaction/backend/jdbc/internal/JdbcResourceLocalTransactionCoordinatorImpl.java

@@ -29,8 +29,8 @@
 import static org.hibernate.internal.CoreLogging.messageLogger;
 
 /**
- * An implementation of TransactionCoordinator based on managing a transaction through the JDBC Connection
+ * An implementation of {@link TransactionCoordinator} based on managing a
- * via {@link JdbcResourceTransaction}
+ * transaction through the JDBC Connection via {@link JdbcResourceTransaction}.
  *
  * @author Steve Ebersole
  *

hibernate-core/src/main/java/org/hibernate/resource/transaction/backend/jdbc/internal/package-info.java

@@ -0,0 +1,12 @@
+/*
+ * 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>.
+ */
+
+/**
+ * An implementation of {@link org.hibernate.resource.transaction.spi.TransactionCoordinator}
+ * based on {@link org.hibernate.resource.transaction.backend.jdbc.spi.JdbcResourceTransaction}.
+ */
+package org.hibernate.resource.transaction.backend.jdbc.internal;

hibernate-core/src/main/java/org/hibernate/resource/transaction/backend/jdbc/package-info.java

@@ -9,12 +9,14 @@
  * Collectively models the concept of transaction coordination through the
  * "data store" specific notion of a transaction.  In Hibernate ORM uses this
  * correlates to the JDBC notion of a transaction, which (unfortunately) is
- * not modeled by an actual contract.  Instead JDBC models transaction control
+ * not modeled by an actual contract.  Instead, JDBC models transaction control
- * via its Connection contract.  Here we use
+ * via its Connection contract.
+ * <p>
+ * Here we use
  * {@link org.hibernate.resource.transaction.backend.jdbc.spi.JdbcResourceTransaction}
  * as the encapsulation for conceptual JDBC transaction.  It also helps isolate the
  * {@link org.hibernate.resource.transaction} and {@link org.hibernate.resource.jdbc}
- * packages from circularity.  Lastly it does somewhat allow for potentially abstracting
+ * packages from circularity.  Lastly, it does somewhat allow for potentially abstracting
  * non-JDBC data stores into this transaction handling utilizing its data store specific
  * transaction mechanism.
  */

hibernate-core/src/main/java/org/hibernate/resource/transaction/backend/jdbc/spi/JdbcResourceTransactionAccess.java

@@ -7,15 +7,17 @@
 package org.hibernate.resource.transaction.backend.jdbc.spi;
 
 /**
- * Provides access to DataStoreTransaction (JDBC transaction stand-in) for use in building resource-local
+ * Provides access to {@link JdbcResourceTransaction} (JDBC transaction stand-in) for use in
- * TransactionCoordinator instances.
+ * building resource-local {@link org.hibernate.resource.transaction.spi.TransactionCoordinator}
+ * instances.
  *
  * @author Steve Ebersole
  */
 public interface JdbcResourceTransactionAccess {
 	/**
-	 * Provides access to the resource local transaction of this data store, which is used by the TransactionCoordinator
+	 * Provides access to the resource local transaction of this data store, which is used by the
-	 * to manage transactions against the data store when not using JTA.
+	 * {@link org.hibernate.resource.transaction.spi.TransactionCoordinator} to manage transactions
+	 * against the data store when not using JTA.
 	 *
 	 * @return The resource-local transaction
 	 */

hibernate-core/src/main/java/org/hibernate/resource/transaction/backend/jdbc/spi/package-info.java

@@ -0,0 +1,15 @@
+/*
+ * 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>.
+ */
+
+/**
+ * An SPI which models the concept of a JDBC resource-level transaction.
+ * <p>
+ * JDBC itself provides no object which represents a transaction.
+ *
+ * @see org.hibernate.resource.transaction.backend.jdbc.spi.JdbcResourceTransaction
+ */
+package org.hibernate.resource.transaction.backend.jdbc.spi;

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

@@ -6,16 +6,17 @@
  */
 
 /**
- * Defines support for dealing with database results, accounting for mixed
+ * Defines support for dealing with results returned from database via JDBC.
- * result sets and update counts hiding the complexity of how this is exposed
+ * <p>
- * via the JDBC API.
+ * Accounts for mixed result sets and update counts, hiding the complexity of how
+ * this is exposed via the JDBC API.
  * <ul>
  * <li>{@link org.hibernate.result.Outputs} represents the overall group of results.
  * <li>{@link org.hibernate.result.Output} represents the mixed individual outcomes,
  *     which might be either a {@link org.hibernate.result.ResultSetOutput} or
  *     a {@link org.hibernate.result.UpdateCountOutput}.
  * </ul>
- *
+ * <p>
  * <pre>
  *     Outputs outputs = ...;
  *     while ( outputs.goToNext() ) {

hibernate-core/src/main/java/org/hibernate/service/internal/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>.
+ */
+
+/**
+ * Implementation of the SPI for integrating pluggable services.
+ */
+package org.hibernate.service.internal;

hibernate-core/src/main/java/org/hibernate/service/spi/InjectService.java

@@ -12,7 +12,7 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Annotation to allow services to request injection of other services
+ * Annotation to allow services to request injection of other services.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/service/spi/ServiceBinding.java

@@ -11,7 +11,7 @@
 import org.jboss.logging.Logger;
 
 /**
- * Models a binding for a particular service
+ * Models a binding for a particular service.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/service/spi/SessionFactoryServiceInitiator.java

@@ -10,7 +10,7 @@
 
 /**
  * Contract for an initiator of services that target the specialized service registry
- * {@link SessionFactoryServiceRegistry}
+ * {@link SessionFactoryServiceRegistry}.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/service/spi/SessionFactoryServiceRegistry.java

@@ -7,8 +7,9 @@
 package org.hibernate.service.spi;
 
 /**
- * Specialized {@link org.hibernate.service.ServiceRegistry} implementation that holds services which need access
+ * Specialized {@link org.hibernate.service.ServiceRegistry} implementation that
- * to the {@link org.hibernate.SessionFactory} during initialization.
+ * holds services which need access to the {@link org.hibernate.SessionFactory}
+ * during initialization.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/service/spi/Wrapped.java

@@ -9,9 +9,10 @@
 import org.hibernate.service.UnknownUnwrapTypeException;
 
 /**
- * Optional contract for services that wrap stuff that to which it is useful to have access.  For example, a service
+ * Optional contract for services that wrap stuff that to which it is useful to have access.
- * that maintains a {@link javax.sql.DataSource} might want to expose access to the {@link javax.sql.DataSource} or
+ * <p>
- * its {@link java.sql.Connection} instances.
+ * For example, a service that maintains a {@link javax.sql.DataSource} might want to expose
+ * access to the {@link javax.sql.DataSource} or its {@link java.sql.Connection} instances.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/sql/ast/package-info.java

@@ -6,7 +6,7 @@
  */
 
 /**
- * Package defining a SQL AST for use in creating and executing various JDBC operations
+ * Package defining a SQL AST for use in creating and executing various JDBC operations.
  */
 @Incubating
 package org.hibernate.sql.ast;

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

@@ -6,6 +6,6 @@
  */
 
 /**
- * Package defining support for creating and consuming SQL AST
+ * Package defining support for creating and consuming a SQL AST.
  */
 package org.hibernate.sql.ast.spi;

hibernate-core/src/main/java/org/hibernate/sql/ast/tree/package-info.java

@@ -8,7 +8,6 @@
 /**
  * Package defining the SQL AST.
  * <p>
- * {@link org.hibernate.sql.ast.spi} defines support for creating and
+ * The package {@link org.hibernate.sql.ast.spi} defines support for creating and consuming the AST.
- * consuming these trees.
  */
 package org.hibernate.sql.ast.tree;

hibernate-core/src/main/java/org/hibernate/sql/exec/internal/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
+ */
+
+/**
+ * Implementation of the SPI for execution of SQL statements via JDBC.
+ */
+package org.hibernate.sql.exec.internal;

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

@@ -6,7 +6,7 @@
  */
 
 /**
- * SPI for execution of SQL statements through JDBC. The statement to execute is
+ * SPI for execution of SQL statements via JDBC. The statement to execute is
  * modelled by {@link org.hibernate.sql.exec.spi.JdbcOperationQuery} and is
  * executed via the corresponding executor.
  * <p>

hibernate-core/src/main/java/org/hibernate/sql/model/ast/AbstractTableMutation.java

@@ -22,7 +22,7 @@
 import org.hibernate.sql.model.jdbc.JdbcMutationOperation;
 
 /**
- * Base TableMutation support
+ * Base {@link TableMutation} support
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/sql/model/ast/package-info.java

@@ -6,7 +6,7 @@
  */
 
 /**
- * SQL AST extensions for model mutations
+ * SQL AST extensions for model mutations.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/sql/model/internal/package-info.java

@@ -6,6 +6,11 @@
  */
 
 /**
+ * Concrete implementations of
+ * {@link org.hibernate.sql.model.ast.MutationGroup},
+ * {@link org.hibernate.sql.model.MutationOperation}, and
+ * {@link org.hibernate.sql.model.ast.TableMutation}.
+ *
  * @author Steve Ebersole
  */
 @Internal

hibernate-core/src/main/java/org/hibernate/sql/model/jdbc/package-info.java

@@ -6,8 +6,7 @@
  */
 
 /**
- * Extensions to {@link org.hibernate.sql.exec.spi.JdbcOperation} for
+ * Extensions to {@link org.hibernate.sql.exec.spi.JdbcOperation} for model mutations.
- * model mutations
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/stat/internal/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
+ */
+
+/**
+ * The built-in implementation of the statistics collection service.
+ */
+package org.hibernate.stat.internal;

hibernate-core/src/main/java/org/hibernate/tool/schema/extract/internal/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>.
+ */
+
+/**
+ * Implementation of the SPI for schema information extraction from the database via JDBC.
+ */
+package org.hibernate.tool.schema.extract.internal;

hibernate-core/src/main/java/org/hibernate/tool/schema/extract/spi/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>.
+ */
+
+/**
+ * Defines an SPI for schema information extraction from the database via JDBC.
+ */
+package org.hibernate.tool.schema.extract.spi;

hibernate-core/src/main/java/org/hibernate/tool/schema/internal/exec/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
+ */
+
+/**
+ * Support for exporting generated DDL to the database or to SQL scripts.
+ */
+package org.hibernate.tool.schema.internal.exec;

hibernate-core/src/main/java/org/hibernate/tool/schema/internal/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
+ */
+
+/**
+ * An implementation of the SPI for the tooling related to DDL generation, export, migration, and validation.
+ */
+package org.hibernate.tool.schema.internal;

hibernate-core/src/main/java/org/hibernate/tool/schema/internal/script/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
+ */
+
+/**
+ * Support for reading SQL scripts supplied to the schema tooling.
+ */
+package org.hibernate.tool.schema.internal.script;

hibernate-core/src/main/java/org/hibernate/tool/schema/spi/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
+ */
+
+/**
+ * An SPI for the tooling related to DDL generation, export, migration, and validation.
+ */
+package org.hibernate.tool.schema.spi;

hibernate-core/src/main/java/org/hibernate/type/descriptor/sql/internal/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>.
+ */
+
+/**
+ * Includes several general-purpose implementations of {@link org.hibernate.type.descriptor.sql.DdlType}.
+ */
+package org.hibernate.type.descriptor.sql.internal;

hibernate-core/src/main/java/org/hibernate/type/descriptor/sql/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>.
+ */
+
+/**
+ * An API for working with abstract families of DDL types
+ * parameterized by varying length, precision, and scale.
+ *
+ * @see org.hibernate.type.descriptor.sql.DdlType
+ */
+package org.hibernate.type.descriptor.sql;

hibernate-core/src/main/java/org/hibernate/type/descriptor/sql/spi/package-info.java

@@ -0,0 +1,13 @@
+/*
+ * 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 a registry for {@link org.hibernate.type.descriptor.sql.DdlType}s.
+ *
+ * @see org.hibernate.type.descriptor.sql.spi.DdlTypeRegistry
+ */
+package org.hibernate.type.descriptor.sql.spi;

hibernate-core/src/main/java/org/hibernate/type/spi/TypeConfiguration.java

@@ -73,18 +73,20 @@
 import static org.hibernate.internal.CoreLogging.messageLogger;
 
 /**
- * Defines a set of available Type instances as isolated from other configurations.  The
+ * Defines a set of available {@link Type} instances as isolated from other configurations.
- * isolation is defined by each instance of a TypeConfiguration.
+ * The isolation is defined by each instance of a {@code TypeConfiguration}.
  * <p>
- * Note that each Type is inherently "scoped" to a TypeConfiguration.  We only ever access
+ * Note that each {@code Type} is inherently "scoped" to a {@code TypeConfiguration}. We only
- * a Type through a TypeConfiguration - specifically the TypeConfiguration in effect for
+ * ever access a {@code Type} via its {@code TypeConfiguration}, more specifically, via the
- * the current persistence unit.
+ * {@code TypeConfiguration} in effect for the current persistence unit.
  * <p>
- * Even though each Type instance is scoped to a TypeConfiguration, Types do not inherently
+ * Even though each {@code Type} instance is scoped to a {@code TypeConfiguration}, a {@code Type}
- * have access to that TypeConfiguration (mainly because Type is an extension contract - meaning
+ * does not inherently have access to its {@code TypeConfiguration}, mainly because {@code Type}
- * that Hibernate does not manage the full set of Types available in ever TypeConfiguration).
+ * is an extension contract and so Hibernate does not have full control over every {@code Type}
- * However Types will often want access to the TypeConfiguration, which can be achieved by the
+ * available in a {@code TypeConfiguration}.
- * Type simply implementing the {@link TypeConfigurationAware} interface.
+ * <p>
+ * However, a {@code Type} will often want access to the  {@code TypeConfiguration}, which can be
+ * achieved by the {@code Type} simply implementing the {@link TypeConfigurationAware} interface.
  *
  * @author Steve Ebersole
  *

hibernate-core/src/main/java/org/hibernate/type/spi/TypeConfigurationAware.java

@@ -7,9 +7,10 @@
 package org.hibernate.type.spi;
 
 /**
- * Optional contract for Types that would like to be part of the scoping process of the
+ * Optional contract for {@link org.hibernate.type.Type}s which would like to be part of the scoping
- * TypeConfiguration, specifically to receive access to the TypeConfiguration it is scoped
+ * process of the {@link TypeConfiguration}, that is, to receive access to the {@code TypeConfiguration}
- * to.  For additional information on TypeConfiguration scoping, see {@link TypeConfiguration}
+ * to which they are scoped. For additional information on {@code TypeConfiguration} scoping, see
+ * {@link TypeConfiguration}.
  * <p>
  * Note that it is illegal for a Type to implement TypeConfigurationAware and at the same time
  * be scoped to more than one TypeConfiguration.  Hibernate will enforce this internally

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

@@ -0,0 +1,13 @@
+/*
+ * 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 a registry for Hibernate {@link org.hibernate.type.Type}s.
+ *
+ * @see org.hibernate.type.spi.TypeConfiguration
+ */
+package org.hibernate.type.spi;