yet more work on the API documentation

- and get rid of people's email addresses, they don't belong in the code

gradle/javadoc.gradle

@@ -13,9 +13,6 @@ apply from: rootProject.file( 'gradle/base-information.gradle' )
 javadoc {
     exclude( "**/internal/*" )
     exclude( "**/generated-src/**" )
-    exclude( "**/sqm/tree/*" )
-    exclude( "**/ast/tree/*" )
-    exclude( "**/sql/results/*" )
 
     final int currentYear = new GregorianCalendar().get( Calendar.YEAR )
 

hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/MimerSQLDialect.java

@@ -54,7 +54,7 @@ import static org.hibernate.type.SqlTypes.VARCHAR;
 /**
  * A dialect for Mimer SQL 11.
  *
- * @author <a href="mailto:fredrik.alund@mimer.se">Fredrik lund</a>
+ * @author Fredrik lund
  * @author Gavin King
  */
 public class MimerSQLDialect extends Dialect {

hibernate-core/src/main/java/org/hibernate/boot/model/internal/JPAIndexHolder.java

@@ -14,7 +14,7 @@ import java.util.StringTokenizer;
 import jakarta.persistence.Index;
 
 /**
- * @author <a href="mailto:stliu@hibernate.org">Strong Liu</a>
+ * @author Strong Liu
  */
 public class JPAIndexHolder {
 	private final String name;

hibernate-core/src/main/java/org/hibernate/boot/model/internal/QueryHintDefinition.java

@@ -28,7 +28,7 @@ import jakarta.persistence.NamedQuery;
 import jakarta.persistence.QueryHint;
 
 /**
- * @author <a href="mailto:stliu@hibernate.org">Strong Liu</a>
+ * @author Strong Liu
  */
 public class QueryHintDefinition {
 	private final String queryName;

hibernate-core/src/main/java/org/hibernate/boot/query/HbmResultSetMappingDescriptor.java

@@ -65,7 +65,7 @@ import org.hibernate.sql.results.graph.entity.EntityValuedFetchable;
 import org.hibernate.type.BasicType;
 
 /**
- * Boot-time descriptor of a result-set mapping as defined in an `hbm.xml` file
+ * Boot-time descriptor of a result set mapping as defined in an {@code hbm.xml} file
  * either implicitly or explicitly
  *
  * @author Steve Ebersole

hibernate-core/src/main/java/org/hibernate/bytecode/enhance/internal/tracker/CompositeOwnerTracker.java

@@ -13,7 +13,7 @@ import org.hibernate.engine.spi.CompositeOwner;
 /**
  * small low memory class to keep references to composite owners
  *
- * @author <a href="mailto:stale.pedersen@jboss.org">Ståle W. Pedersen</a>
+ * @author Ståle W. Pedersen
  */
 public final class CompositeOwnerTracker {
 

hibernate-core/src/main/java/org/hibernate/bytecode/enhance/internal/tracker/DirtyTracker.java

@@ -9,7 +9,7 @@ package org.hibernate.bytecode.enhance.internal.tracker;
 /**
  * Interface to be implemented by dirty trackers, a simplified Set of String.
  *
- * @author <a href="mailto:lbarreiro@redhat.com">Luis Barreiro</a>
+ * @author Luis Barreiro
  */
 public interface DirtyTracker {
 

hibernate-core/src/main/java/org/hibernate/bytecode/enhance/internal/tracker/NoopCollectionTracker.java

@@ -11,7 +11,7 @@ import org.hibernate.bytecode.enhance.spi.CollectionTracker;
 /**
  * small low memory class to keep track of the number of elements in a collection
  *
- * @author <a href="mailto:stale.pedersen@jboss.org">Ståle W. Pedersen</a>
+ * @author Ståle W. Pedersen
  */
 public final class NoopCollectionTracker implements CollectionTracker {
 

hibernate-core/src/main/java/org/hibernate/bytecode/enhance/internal/tracker/SimpleCollectionTracker.java

@@ -14,7 +14,7 @@ import org.hibernate.internal.util.collections.ArrayHelper;
 /**
  * small low memory class to keep track of the number of elements in a collection
  *
- * @author <a href="mailto:stale.pedersen@jboss.org">Ståle W. Pedersen</a>
+ * @author Ståle W. Pedersen
  */
 public final class SimpleCollectionTracker implements CollectionTracker {
 

hibernate-core/src/main/java/org/hibernate/bytecode/enhance/internal/tracker/SimpleFieldTracker.java

@@ -16,7 +16,7 @@ import org.hibernate.internal.util.collections.ArrayHelper;
  * uses an array as a set (under the assumption that the number of elements will be low) to avoid having to instantiate an HashSet.
  * if the assumption does not, hold the array can be kept ordered to reduce the cost of verifying duplicates
  *
- * @author <a href="mailto:lbarreiro@redhat.com">Luis Barreiro</a>
+ * @author Luis Barreiro
  */
 public final class SimpleFieldTracker implements DirtyTracker {
 

hibernate-core/src/main/java/org/hibernate/bytecode/enhance/internal/tracker/SortedFieldTracker.java

@@ -13,7 +13,7 @@ import org.hibernate.internal.util.collections.ArrayHelper;
  *
  * similar to BasicTracker but where the array is kept ordered to reduce the cost of verifying duplicates
  *
- * @author <a href="mailto:lbarreiro@redhat.com">Luis Barreiro</a>
+ * @author Luis Barreiro
  */
 public final class SortedFieldTracker implements DirtyTracker {
 

hibernate-core/src/main/java/org/hibernate/bytecode/enhance/spi/CollectionTracker.java

@@ -9,7 +9,7 @@ package org.hibernate.bytecode.enhance.spi;
 /**
  * Interface to be implemented by collection trackers that hold the expected size od collections, a simplified {@code Map<String, int>}.
  *
- * @author <a href="mailto:lbarreiro@redhat.com">Luis Barreiro</a>
+ * @author Luis Barreiro
  */
 public interface CollectionTracker {
 

hibernate-core/src/main/java/org/hibernate/bytecode/enhance/spi/DefaultEnhancementContext.java

@@ -19,7 +19,7 @@ import jakarta.persistence.Transient;
 /**
  * default implementation of EnhancementContext. May be sub-classed as needed.
  *
- * @author <a href="mailto:lbarreiro@redhat.com">Luis Barreiro</a>
+ * @author Luis Barreiro
  */
 public class DefaultEnhancementContext implements EnhancementContext {
 

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

@@ -6,6 +6,6 @@
  */
 
 /**
- * interceptor implementations
+ * Support for bytecode interceptor implementations.
  */
 package org.hibernate.bytecode.enhance.spi.interceptor;

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

@@ -6,6 +6,6 @@
  */
 
 /**
- * package defining bytecode code enhancement (instrumentation) support.
+ * Package defining bytecode code enhancement (instrumentation) support.
  */
 package org.hibernate.bytecode.enhance.spi;

hibernate-core/src/main/java/org/hibernate/bytecode/spi/ClassTransformer.java

@@ -11,22 +11,25 @@ import java.security.ProtectionDomain;
 import jakarta.persistence.spi.TransformerException;
 
 /**
- * A persistence provider provides an instance of this interface
+ * A persistence provider provides an instance of this interface to the
- * to the PersistenceUnitInfo.addTransformer method.
+ * {@link jakarta.persistence.spi.PersistenceUnitInfo#addTransformer} method.
- * The supplied transformer instance will get called to transform
+ * The supplied transformer instance will get called to transform entity class
- * entity class files when they are loaded and redefined.  The transformation
+ * files when they are loaded and redefined. The transformation occurs before
- * occurs before the class is defined by the JVM
+ * the class is defined by the JVM.
  *
- * @author <a href="mailto:bill@jboss.org">Bill Burke</a>
+ * @author Bill Burke
  * @author Emmanuel Bernard
  */
 public interface ClassTransformer extends jakarta.persistence.spi.ClassTransformer {
 	/**
-	 * Invoked when a class is being loaded or redefined to add hooks for persistence bytecode manipulation.
+	 * Invoked when a class is being loaded or redefined to add hooks for persistence
+	 * bytecode manipulation.
 	 *
-	 * @param loader the defining class loader of the class being transformed.  It may be null if using bootstrap loader
+	 * @param loader The defining class loader of the class being transformed.
+	 *               It may be null if using bootstrap loader
 	 * @param className The name of the class being transformed
-	 * @param classBeingRedefined If an already loaded class is being redefined, then pass this as a parameter
+	 * @param classBeingRedefined If an already loaded class is being redefined,
+	 *                            then pass this as a parameter
 	 * @param protectionDomain ProtectionDomain of the class being (re)-defined
 	 * @param classfileBuffer The input byte buffer in class file format
 	 * @return A well-formed class file that can be loaded

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

@@ -6,6 +6,6 @@
  */
 
 /**
- * Internal implementations and support for persistent collections
+ * Internal implementations and support for persistent collections.
  */
 package org.hibernate.collection.internal;

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

@@ -6,11 +6,13 @@
  */
 
 /**
- * This package defines a framework for collection wrappers. The
+ * This package defines a framework for lazy-initializing and state-tracking
- * interface {@link org.hibernate.collection.spi.PersistentCollection}
+ * collection wrappers.
- * and all its implementations belong to an SPI. They are not part of
+ * <p>
- * the public API of Hibernate, and are not meant to be used directly
+ * The interface {@link org.hibernate.collection.spi.PersistentCollection}
- * by typical programs which use Hibernate for persistence.
+ * and all its implementations belong to an SPI. They are not part of the
+ * public API of Hibernate, and are not meant to be used directly by typical
+ * programs which use Hibernate for persistence.
  *
  * @see org.hibernate.proxy
  */

hibernate-core/src/main/java/org/hibernate/collection/spi/CollectionInitializerProducer.java

@@ -16,7 +16,7 @@ import org.hibernate.sql.results.graph.FetchParentAccess;
 import org.hibernate.sql.results.graph.collection.CollectionInitializer;
 
 /**
- * Functional contract to create a CollectionInitializer
+ * Functional contract to create a {@link CollectionInitializer}.
  *
  * @author Steve Ebersole
  *
@@ -26,15 +26,20 @@ import org.hibernate.sql.results.graph.collection.CollectionInitializer;
 @FunctionalInterface
 public interface CollectionInitializerProducer {
 	/**
-	 * Create an initializer for `attribute` relative to `navigablePath`.
+	 * Create an initializer for the given attribute relative to the given
+	 * navigable path.
 	 *
-	 * `parentAccess` may be null to indicate that the initializer is for
+	 * @param navigablePath the navigable path
-	 * a {@link org.hibernate.sql.results.graph.DomainResult} rather than
+	 * @param attribute the attribute
-	 * a {@link org.hibernate.sql.results.graph.Fetch}
+	 * @param parentAccess  may be null to indicate that the initializer is
-	 *
+	 *        for a {@link org.hibernate.sql.results.graph.DomainResult}
-	 * `collectionKeyAssembler` and `collectionValueKeyAssembler` allow
+	 *        rather than a {@link org.hibernate.sql.results.graph.Fetch}
-	 * creating {@link org.hibernate.sql.results.graph.DomainResult} for
+	 * @param collectionKeyAssembler allows creation of a
-	 * either side of the collection foreign-key
+	 *        {@link org.hibernate.sql.results.graph.DomainResult} for
+	 *        either side of the collection foreign key
+	 * @param collectionValueKeyAssembler allows creation of a
+	 *        {@link org.hibernate.sql.results.graph.DomainResult} for
+	 *        either side of the collection foreign key
 	 */
 	CollectionInitializer produceInitializer(
 			NavigablePath navigablePath,

hibernate-core/src/main/java/org/hibernate/collection/spi/CollectionSemantics.java

@@ -20,10 +20,12 @@ import org.hibernate.sql.results.graph.Fetch;
 import org.hibernate.sql.results.graph.FetchParent;
 
 /**
- * Describes the semantics of a persistent collection such that Hibernate
+ * Each instance of this interface describes the semantics of some sort of
- * understands how to use it - create one, handle elements, etc.
+ * persistent collection so that Hibernate understands how to manage the
- *
+ * lifecycle of instances of that sort of collection.
- * @apiNote The described collection need not be part of the "Java Collection Framework"
+ * <p>
+ * A collection type with semantics described by a {@code CollectionSemantics}
+ * object need not be part of the Java Collections Framework.
  *
  * @param <E> the collection element or map key type
  * @param <CE> the type of the collection

hibernate-core/src/main/java/org/hibernate/collection/spi/CollectionSemanticsResolver.java

@@ -10,13 +10,12 @@ import org.hibernate.Incubating;
 import org.hibernate.mapping.Collection;
 
 /**
- * Resolve the collection semantics for the given mapped collection
+ * Resolve the collection semantics for the given mapped collection.
  *
- * todo (6.0) ...
+ * @apiNote Ideally, this would act as the contract that allows pluggable
- *
+ *          resolution of non-Java Collection types, perhaps as part of a
- * Ideally would act as the contract that allows pluggable resolution of
+ *          generalized reflection on the attribute to determine its
- * non-Java Collection types - maybe as part of a generalized reflection
+ *          nature/classification
- * on the attribute to determine its nature/classification
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/collection/spi/InitializerProducerBuilder.java

@@ -36,29 +36,23 @@ public class InitializerProducerBuilder {
 			Fetch elementFetch,
 			DomainResultCreationState creationState) {
 		switch ( classification ) {
-			case ARRAY: {
+			case ARRAY:
 				return createArrayInitializerProducer( navigablePath, attributeMapping, fetchParent, selected, indexFetch, elementFetch, creationState );
-			}
 			case BAG:
-			case ID_BAG: {
+			case ID_BAG:
 				return createBagInitializerProducer( navigablePath, attributeMapping, fetchParent, selected, elementFetch, creationState );
-			}
+			case LIST:
-			case LIST: {
 				return createListInitializerProducer( navigablePath, attributeMapping, fetchParent, selected, indexFetch, elementFetch, creationState );
-			}
 			case MAP:
 			case ORDERED_MAP:
-			case SORTED_MAP: {
+			case SORTED_MAP:
 				return createMapInitializerProducer( navigablePath, attributeMapping, fetchParent, selected, indexFetch, elementFetch, creationState );
-			}
 			case SET:
 			case ORDERED_SET:
-			case SORTED_SET: {
+			case SORTED_SET:
 				return createSetInitializerProducer( navigablePath, attributeMapping, fetchParent, selected, elementFetch, creationState );
-			}
+			default:
-			default: {
 				throw new IllegalArgumentException( "Unknown CollectionClassification : " + classification );
-			}
 		}
 	}
 
@@ -228,7 +222,7 @@ public class InitializerProducerBuilder {
 			Fetch elementFetch,
 			DomainResultCreationState creationState) {
 		switch ( classification ) {
-			case ARRAY: {
+			case ARRAY:
 				return createArrayInitializerProducer(
 						navigablePath,
 						attributeMapping,
@@ -238,9 +232,8 @@ public class InitializerProducerBuilder {
 						elementFetch,
 						creationState
 				);
-			}
 			case BAG:
-			case ID_BAG: {
+			case ID_BAG:
 				assert indexFetch == null;
 				return createBagInitializerProducer(
 						navigablePath,
@@ -250,8 +243,7 @@ public class InitializerProducerBuilder {
 						elementFetch,
 						creationState
 				);
-			}
+			case LIST:
-			case LIST: {
 				return createListInitializerProducer(
 						navigablePath,
 						attributeMapping,
@@ -261,10 +253,9 @@ public class InitializerProducerBuilder {
 						elementFetch,
 						creationState
 				);
-			}
 			case MAP:
 			case ORDERED_MAP:
-			case SORTED_MAP: {
+			case SORTED_MAP:
 				return createMapInitializerProducer(
 						navigablePath,
 						attributeMapping,
@@ -274,10 +265,9 @@ public class InitializerProducerBuilder {
 						elementFetch,
 						creationState
 				);
-			}
 			case SET:
 			case ORDERED_SET:
-			case SORTED_SET: {
+			case SORTED_SET:
 				return createSetInitializerProducer(
 						navigablePath,
 						attributeMapping,
@@ -286,10 +276,8 @@ public class InitializerProducerBuilder {
 						elementFetch,
 						creationState
 				);
-			}
+			default:
-			default: {
 				throw new IllegalArgumentException( "Unknown CollectionClassification : " + classification );
-			}
 		}
 	}
 

hibernate-core/src/main/java/org/hibernate/collection/spi/LazyInitializable.java

@@ -9,9 +9,21 @@ package org.hibernate.collection.spi;
 import org.hibernate.Incubating;
 
 /**
- * Hibernate "wraps" a java collection in an instance of PersistentCollection. Envers uses custom collection
+ * The most general abstraction over collections which may be fetched lazily.
- * wrappers (ListProxy, SetProxy, etc). All of them need to extend LazyInitializable, so the
+ * <ul>
- * Hibernate.isInitialized method can check if the collection is initialized or not.
+ * <li>Hibernate core "wraps" a Java collection in an instance of
+ *     {@link PersistentCollection}.
+ * <li>Similarly, Envers uses its own custom collection wrappers:
+ *     {@code ListProxy}, {@code SetProxy}, and friends).
+ * </ul>
+ * <p>
+ * All of these wrapper objects extend {@code LazyInitializable}, allowing:
+ * <ul>
+ * <li>the method {@link org.hibernate.Hibernate#isInitialized(Object)} to
+ *     determine if the collection was already fetched, and
+ * <li>the method {@link org.hibernate.Hibernate#initialize(Object)} to
+ *     force it to be fetched.
+ * </ul>
  * 
  * @author Fabricio Gregorio
  */
@@ -22,11 +34,15 @@ public interface LazyInitializable {
 	 * Is this instance initialized?
 	 *
 	 * @return Was this collection initialized? Or is its data still not (fully) loaded?
+	 *
+	 * @see org.hibernate.Hibernate#isInitialized(Object)
 	 */
 	boolean wasInitialized();
 	
 	/**
 	 * To be called internally by the session, forcing immediate initialization.
+	 *
+	 * @see org.hibernate.Hibernate#initialize(Object)
 	 */
 	void forceInitialization();
 

hibernate-core/src/main/java/org/hibernate/collection/spi/MapSemantics.java

@@ -12,7 +12,7 @@ import java.util.function.BiConsumer;
 import java.util.function.Consumer;
 
 /**
- * Extension of CollectionSemantics for Maps
+ * Extension of {@link CollectionSemantics} for Maps
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/collection/spi/PersistentArrayHolder.java

@@ -24,12 +24,13 @@ import org.hibernate.persister.collection.CollectionPersister;
 import org.hibernate.type.Type;
 
 /**
- * A persistent wrapper for an array. Lazy initialization
+ * A dummy collection wrapper for an array. Lazy initialization is
- * is NOT supported. Use of Hibernate arrays is not really
+ * <em>not</em> supported. The use of arrays to represent persistent
- * recommended.
+ * collections in Hibernate is discouraged.
  *
- * @apiNote Incubating in terms of making this non-internal.  These contracts
+ * @apiNote Incubating in terms of making this non-internal.
- * will be getting cleaned up in following releases.
+ *          These contracts will be getting cleaned up in following
+ *          releases.
  *
  * @author Gavin King
  */

hibernate-core/src/main/java/org/hibernate/collection/spi/PersistentBag.java

@@ -26,13 +26,15 @@ import org.hibernate.persister.collection.CollectionPersister;
 import org.hibernate.type.Type;
 
 /**
- * An unordered, unkeyed collection that can contain the same element
+ * An unordered, un-keyed collection that can contain the same element
- * multiple times. The Java collections API, curiously, has no {@code Bag}.
+ * multiple times. The Java Collections Framework, curiously, has no
- * Most developers seem to use {@code List}s to represent bag semantics,
+ * {@code Bag} interface. It is, however, common to use {@code List}s
- * so Hibernate follows this practice.
+ * to represent a collection with bag semantics, so Hibernate follows
+ * this practice.
  *
- * @apiNote Incubating in terms of making this non-internal.  These contracts
+ * @apiNote Incubating in terms of making this non-internal.
- * will be getting cleaned up in following releases.
+ *          These contracts will be getting cleaned up in following
+ *          releases.
  *
  * @author Gavin King
  */

hibernate-core/src/main/java/org/hibernate/collection/spi/PersistentCollection.java

@@ -21,26 +21,29 @@ import org.hibernate.type.Type;
 
 /**
  * Persistent collections are treated as value objects by Hibernate.
- * ie. they have no independent existence beyond the object holding
+ * They have no independent existence beyond the entity holding a
- * a reference to them. Unlike instances of entity classes, they are
+ * reference to them. Unlike instances of entity classes, they are
  * automatically deleted when unreferenced and automatically become
  * persistent when held by a persistent object. Collections can be
  * passed between different objects (change "roles") and this might
  * cause their elements to move from one database table to another.
  * <p>
- * Hibernate "wraps" a java collection in an instance of
+ * Hibernate "wraps" a Java collection in an instance of
- * PersistentCollection. This mechanism is designed to support
+ * {@code PersistentCollection}. This mechanism is allows for
- * tracking of changes to the collection's persistent state and
+ * tracking of changes to the persistent state of the collection and
- * lazy instantiation of collection elements. The downside is that
+ * lazy fetching of the collection elements. The downside is that
  * only certain abstract collection types are supported and any
- * extra semantics are lost
+ * extra semantics associated with the particular implementation of
+ * the generic collection type are lost. For example, every
+ * {@link java.util.List} behaves like an {@code ArrayList}, and
+ * every {@link java.util.SortedMap} behaves like a {@code TreeMap}.
  * <p>
  * Applications should <em>never</em> use classes in this package
  * directly, unless extending the "framework" here.
  * <p>
- * Changes to <em>structure</em> of the collection are recorded by the
+ * Changes to <em>structure</em> of the collection are recorded by
- * collection calling back to the session. Changes to mutable
+ * the collection calling back to the session. Changes to mutable
- * elements (ie. composite elements) are discovered by cloning their
+ * elements (composite elements) are discovered by cloning their
  * state when the collection is initialized and comparing at flush
  * time.
  *

hibernate-core/src/main/java/org/hibernate/collection/spi/PersistentIdentifierBag.java

@@ -26,17 +26,18 @@ import org.hibernate.type.Type;
 import static org.hibernate.generator.EventType.INSERT;
 
 /**
- * An {@code IdentifierBag} implements "bag" semantics more efficiently than
+ * An "identifier bag" implements "bag" semantics more efficiently than a
- * a regular {@code Bag} by adding a synthetic identifier column to the
+ * regular bag by adding a synthetic identifier column to the table. This
- * table. This identifier is unique for all rows in the table, allowing very
+ * identifier is unique over all rows in the table, allowing very efficient
- * efficient updates and deletes. The value of the identifier is never exposed
+ * updates and deletes. The value of the identifier is never exposed to the
- * to the application.
+ * application.
  * <p>
- * {@code IdentifierBag}s may not be used for a many-to-one association.
+ * Identifier bags may not be used for a many-to-one association.
  * Furthermore, there is no reason to use {@code inverse="true"}.
  *
- * @apiNote Incubating in terms of making this non-internal.  These contracts
+ * @apiNote Incubating in terms of making this non-internal.
- * will be getting cleaned up in following releases.
+ *          These contracts will be getting cleaned up in following
+ *          releases.
  *
  * @author Gavin King
  */

hibernate-core/src/main/java/org/hibernate/collection/spi/PersistentList.java

@@ -23,11 +23,12 @@ import org.hibernate.persister.collection.CollectionPersister;
 import org.hibernate.type.Type;
 
 /**
- * A persistent wrapper for a {@code java.util.List}. Underlying
+ * A persistent wrapper for a {@link java.util.List}. Underlying
  * collection is an {@code ArrayList}.
  *
- * @apiNote Incubating in terms of making this non-internal.  These contracts
+ * @apiNote Incubating in terms of making this non-internal.
- * will be getting cleaned up in following releases.
+ *          These contracts will be getting cleaned up in following
+ *          releases.
  *
  * @author Gavin King
  */

hibernate-core/src/main/java/org/hibernate/collection/spi/PersistentMap.java

@@ -28,11 +28,12 @@ import org.hibernate.type.Type;
 
 
 /**
- * A persistent wrapper for a {@code java.util.Map}. Underlying collection
+ * A persistent wrapper for a {@link java.util.Map}. Underlying collection
  * is a {@code HashMap}.
  *
- * @apiNote Incubating in terms of making this non-internal.  These contracts
+ * @apiNote Incubating in terms of making this non-internal.
- * will be getting cleaned up in following releases.
+ *          These contracts will be getting cleaned up in following
+ *          releases.
  *
  * @author Gavin King
  */

hibernate-core/src/main/java/org/hibernate/collection/spi/PersistentSet.java

@@ -26,11 +26,12 @@ import org.hibernate.type.Type;
 
 
 /**
- * A persistent wrapper for a {@code java.util.Set}. The underlying
+ * A persistent wrapper for a {@link java.util.Set}. The underlying
  * collection is a {@code HashSet}.
  *
- * @apiNote Incubating in terms of making this non-internal.  These contracts
+ * @apiNote Incubating in terms of making this non-internal.
- * will be getting cleaned up in following releases.
+ *          These contracts will be getting cleaned up in following
+ *          releases.
  *
  * @author Gavin King
  */

hibernate-core/src/main/java/org/hibernate/collection/spi/PersistentSortedMap.java

@@ -20,13 +20,14 @@ import org.hibernate.engine.spi.SharedSessionContractImplementor;
 import org.hibernate.persister.collection.BasicCollectionPersister;
 
 /**
- * A persistent wrapper for a {@code java.util.SortedMap}. Underlying
+ * A persistent wrapper for a {@link java.util.SortedMap}. Underlying
  * collection is a {@code TreeMap}.
  *
- * @apiNote Incubating in terms of making this non-internal.  These contracts
+ * @apiNote Incubating in terms of making this non-internal.
- * will be getting cleaned up in following releases.
+ *          These contracts will be getting cleaned up in following
+ *          releases.
  *
- * @author <a href="mailto:doug.currie@alum.mit.edu">e</a>
+ * @author Doug Currie
  */
 @Incubating
 public class PersistentSortedMap<K,E> extends PersistentMap<K,E> implements SortedMap<K,E> {

hibernate-core/src/main/java/org/hibernate/collection/spi/PersistentSortedSet.java

@@ -17,13 +17,14 @@ import org.hibernate.engine.spi.SharedSessionContractImplementor;
 import org.hibernate.persister.collection.BasicCollectionPersister;
 
 /**
- * A persistent wrapper for a {@code java.util.SortedSet}. Underlying
+ * A persistent wrapper for a {@link java.util.SortedSet}. Underlying
  * collection is a {@code TreeSet}.
  *
- * @apiNote Incubating in terms of making this non-internal.  These contracts
+ * @apiNote Incubating in terms of making this non-internal.
- * will be getting cleaned up in following releases.
+ *          These contracts will be getting cleaned up in following
+ *          releases.
  *
- * @author <a href="mailto:doug.currie@alum.mit.edu">e</a>
+ * @author Doug Currie
  */
 @Incubating
 public class PersistentSortedSet<E> extends PersistentSet<E> implements SortedSet<E> {

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

@@ -6,6 +6,15 @@
  */
 
 /**
- * SPI definitions for persistent collections.
+ * This package defines the SPI of a framework for lazy-initializing
+ * and state-tracking collection wrappers.
+ * <p>
+ * The interface {@link org.hibernate.collection.spi.PersistentCollection}
+ * and all its implementations belong to an SPI. They are not part of the
+ * public API of Hibernate, and are not meant to be used directly by typical
+ * programs which use Hibernate for persistence.
+ *
+ * @see org.hibernate.collection.spi.PersistentCollection
+ * @see org.hibernate.collection.spi.CollectionSemantics
  */
 package org.hibernate.collection.spi;

hibernate-core/src/main/java/org/hibernate/dialect/AbstractHANADialect.java

@@ -160,8 +160,8 @@ import static org.hibernate.type.descriptor.DateTimeUtils.appendAsTimestampWithM
  * <p>
  * Note: This dialect is configured to create foreign keys with {@code on update cascade}.
  *
- * @author <a href="mailto:andrew.clemons@sap.com">Andrew Clemons</a>
+ * @author Andrew Clemons
- * @author <a href="mailto:jonathan.bregler@sap.com">Jonathan Bregler</a>
+ * @author Jonathan Bregler
  */
 public abstract class AbstractHANADialect extends Dialect {
 	private static final CoreMessageLogger LOG = CoreLogging.messageLogger( AbstractHANADialect.class );

hibernate-core/src/main/java/org/hibernate/dialect/HANACloudColumnStoreDialect.java

@@ -17,7 +17,7 @@ package org.hibernate.dialect;
  * <p>
  * Column tables are created by this dialect when using the auto-ddl feature.
  * 
- * @author <a href="mailto:jonathan.bregler@sap.com">Jonathan Bregler</a>
+ * @author Jonathan Bregler
  *
  * @deprecated use HANAColumnStoreDialect(400)
  */

hibernate-core/src/main/java/org/hibernate/dialect/HANAColumnStoreDialect.java

@@ -32,8 +32,8 @@ import static org.hibernate.query.sqm.produce.function.FunctionParameterType.ANY
  * <p>
  * Column tables are created by this dialect when using the auto-ddl feature.
  * 
- * @author <a href="mailto:andrew.clemons@sap.com">Andrew Clemons</a>
+ * @author Andrew Clemons
- * @author <a href="mailto:jonathan.bregler@sap.com">Jonathan Bregler</a>
+ * @author Jonathan Bregler
  */
 public class HANAColumnStoreDialect extends AbstractHANADialect {
 

hibernate-core/src/main/java/org/hibernate/dialect/HANARowStoreDialect.java

@@ -27,8 +27,8 @@ import org.hibernate.query.sqm.mutation.spi.SqmMultiTableMutationStrategy;
  * <p>
  * Row tables are created by this dialect when using the auto-ddl feature.
  *
- * @author <a href="mailto:andrew.clemons@sap.com">Andrew Clemons</a>
+ * @author Andrew Clemons
- * @author <a href="mailto:jonathan.bregler@sap.com">Jonathan Bregler</a>
+ * @author Jonathan Bregler
  */
 public class HANARowStoreDialect extends AbstractHANADialect {
 

hibernate-core/src/main/java/org/hibernate/engine/internal/AbstractEntityEntry.java

@@ -41,9 +41,9 @@ import static org.hibernate.engine.internal.ManagedTypeHelper.isPersistentAttrib
  * A base implementation of EntityEntry
  *
  * @author Gavin King
- * @author <a href="mailto:emmanuel@hibernate.org">Emmanuel Bernard</a>
+ * @author Emmanuel Bernard
  * @author Gunnar Morling
- * @author <a href="mailto:sanne@hibernate.org">Sanne Grinovero </a>
+ * @author Sanne Grinovero
  */
 public abstract class AbstractEntityEntry implements Serializable, EntityEntry {
 

hibernate-core/src/main/java/org/hibernate/engine/internal/EntityEntryExtraStateHolder.java

@@ -11,7 +11,7 @@ import org.hibernate.engine.spi.EntityEntryExtraState;
 /**
  * Contains optional state from {@link org.hibernate.engine.spi.EntityEntry}.
  *
- * @author <a href="mailto:emmanuel@hibernate.org">Emmanuel Bernard</a>
+ * @author Emmanuel Bernard
  */
 public class EntityEntryExtraStateHolder implements EntityEntryExtraState {
 	private EntityEntryExtraState next;

hibernate-core/src/main/java/org/hibernate/engine/internal/ImmutableEntityEntry.java

@@ -23,9 +23,9 @@ import org.hibernate.persister.entity.EntityPersister;
  * immutable in terms of its internal state; the term immutable here refers to the entity it describes.
  *
  * @author Gavin King
- * @author <a href="mailto:emmanuel@hibernate.org">Emmanuel Bernard</a>
+ * @author Emmanuel Bernard
  * @author Gunnar Morling
- * @author <a href="mailto:sanne@hibernate.org">Sanne Grinovero </a>
+ * @author Sanne Grinovero
  *
  * @see org.hibernate.annotations.Immutable
  */

hibernate-core/src/main/java/org/hibernate/engine/internal/MutableEntityEntry.java

@@ -20,9 +20,9 @@ import org.hibernate.persister.entity.EntityPersister;
  * An EntityEntry implementation for mutable entities.
  *
  * @author Gavin King
- * @author <a href="mailto:emmanuel@hibernate.org">Emmanuel Bernard</a>
+ * @author Emmanuel Bernard
  * @author Gunnar Morling
- * @author <a href="mailto:sanne@hibernate.org">Sanne Grinovero </a>
+ * @author Sanne Grinovero
  */
 public final class MutableEntityEntry extends AbstractEntityEntry {
 

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

@@ -6,6 +6,6 @@
  */
 
 /**
- * Internals for accessing JDBC Connections
+ * Various implementations of the SPI contracts for obtaining JDBC {@link java.sql.Connection}s.
  */
 package org.hibernate.engine.jdbc.connections.internal;

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

@@ -6,6 +6,9 @@
  */
 
 /**
- * Defines contracts for accessing JDBC Connections
+ * Defines SPI contracts for obtaining JDBC {@link java.sql.Connection}s from a
+ * provider implemented as a {@linkplain org.hibernate.service.Service service}.
+ *
+ * @see org.hibernate.engine.jdbc.connections.spi.ConnectionProvider
  */
 package org.hibernate.engine.jdbc.connections.spi;

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

@@ -6,6 +6,6 @@
  */
 
 /**
- * Support for various aspects of JDBC interaction
+ * Support for various aspects of JDBC interaction.
  */
 package org.hibernate.engine.jdbc;

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

@@ -6,6 +6,6 @@
  */
 
 /**
- * SPI contracts for supporting various aspects of JDBC interaction
+ * SPI contracts supporting various aspects of JDBC interaction.
  */
 package org.hibernate.engine.jdbc.spi;

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

@@ -6,6 +6,6 @@
  */
 
 /**
- * The SPI contracts for Hibernate JNDI support
+ * The SPI contracts for integration with JNDI.
  */
 package org.hibernate.engine.jndi.spi;

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

@@ -6,6 +6,6 @@
  */
 
 /**
- * Models the fetch profiles defined by the application
+ * Models the fetch profiles defined by the application.
  */
 package org.hibernate.engine.profile;

hibernate-core/src/main/java/org/hibernate/engine/spi/CompositeOwner.java

@@ -7,7 +7,7 @@
 package org.hibernate.engine.spi;
 
 /**
- * @author <a href="mailto:stale.pedersen@jboss.org">Ståle W. Pedersen</a>
+ * @author Ståle W. Pedersen
  */
 public interface CompositeOwner extends PrimeAmongSecondarySupertypes {
 	/**

hibernate-core/src/main/java/org/hibernate/engine/spi/CompositeTracker.java

@@ -7,7 +7,7 @@
 package org.hibernate.engine.spi;
 
 /**
- * @author <a href="mailto:stale.pedersen@jboss.org">Ståle W. Pedersen</a>
+ * @author Ståle W. Pedersen
  */
 public interface CompositeTracker extends PrimeAmongSecondarySupertypes {
 

hibernate-core/src/main/java/org/hibernate/engine/spi/EntityEntry.java

@@ -20,9 +20,9 @@ import org.hibernate.persister.entity.EntityPersister;
  * therefore we need to take care of its impact on memory consumption.
  *
  * @author Gavin King
- * @author <a href="mailto:emmanuel@hibernate.org">Emmanuel Bernard</a>
+ * @author Emmanuel Bernard
  * @author Gunnar Morling
- * @author <a href="mailto:sanne@hibernate.org">Sanne Grinovero </a>
+ * @author Sanne Grinovero
  */
 public interface EntityEntry {
 	LockMode getLockMode();

hibernate-core/src/main/java/org/hibernate/engine/spi/EntityEntryExtraState.java

@@ -10,7 +10,7 @@ package org.hibernate.engine.spi;
 /**
  * Navigation methods for extra state objects attached to {@link EntityEntry}.
  *
- * @author <a href="mailto:emmanuel@hibernate.org">Emmanuel Bernard</a>
+ * @author Emmanuel Bernard
  */
 public interface EntityEntryExtraState {
 

hibernate-core/src/main/java/org/hibernate/engine/spi/PrimeAmongSecondarySupertypes.java

@@ -6,18 +6,20 @@
  */
 package org.hibernate.engine.spi;
 
+import org.hibernate.Internal;
 import org.hibernate.engine.internal.ManagedTypeHelper;
 import org.hibernate.proxy.HibernateProxy;
 import org.hibernate.proxy.ProxyConfiguration;
 
 /**
- * For a full explanation of the purpose of this interface
+ * For a full explanation of the purpose of this interface see {@link ManagedTypeHelper}.
- * see {@link ManagedTypeHelper}.
+ *
- * This is an internal, private marking interface; it's exposed in the spi
+ * @apiNote This is an internal, private marking interface; it's exposed in the SPI
- * package as bytecode enhanced usercode needs to be able to refer to it.
+ *          package as bytecode enhanced user code needs to be able to reference it.
  *
  * @author Sanne Grinovero
  */
+@Internal
 public interface PrimeAmongSecondarySupertypes {
 
 	default ManagedEntity asManagedEntity() {

hibernate-core/src/main/java/org/hibernate/engine/spi/SelfDirtinessTracker.java

@@ -16,7 +16,7 @@ import org.hibernate.bytecode.enhance.spi.CollectionTracker;
  * also introduced into the entity when using bytecode enhancement and requesting
  * that entities track their own dirtiness.
  *
- * @author <a href="mailto:stale.pedersen@jboss.org">Ståle W. Pedersen</a>
+ * @author Ståle W. Pedersen
  */
 public interface SelfDirtinessTracker extends PrimeAmongSecondarySupertypes {
 	/**

hibernate-core/src/main/java/org/hibernate/engine/spi/SessionLazyDelegator.java

@@ -61,7 +61,7 @@ import jakarta.persistence.metamodel.Metamodel;
  * Another difference with SessionDelegatorBaseImpl is that
  * this type only implements Session.
  *
- * @author <a href="mailto:sanne@hibernate.org">Sanne Grinovero</a> (C) 2022 Red Hat Inc.
+ * @author Sanne Grinovero
  */
 public class SessionLazyDelegator implements Session {
 

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

@@ -35,7 +35,7 @@ import org.hibernate.HibernateException;
  * This class is reported to work on WAS version 6 in any of the standard J2EE/Java EE component containers.
  *
  * @author Gavin King
- * @author <a href="mailto:jesper@udby.com>Jesper Udby</a>
+ * @author Jesper Udby
  * @author Steve Ebersole
  */
 public class WebSphereExtendedJtaPlatform extends AbstractJtaPlatform {

hibernate-core/src/main/java/org/hibernate/event/internal/PostDeleteEventListenerStandardImpl.java

@@ -16,7 +16,7 @@ import org.hibernate.persister.entity.EntityPersister;
 /**
  * The standard PostDeleteEventListener implementation
  *
- * @author <a href="mailto:kabir.khan@jboss.org">Kabir Khan</a>
+ * @author Kabir Khan
  * @author Steve Ebersole
  */
 public class PostDeleteEventListenerStandardImpl implements PostDeleteEventListener, CallbackRegistryConsumer {

hibernate-core/src/main/java/org/hibernate/event/internal/PostInsertEventListenerStandardImpl.java

@@ -14,7 +14,7 @@ import org.hibernate.jpa.event.spi.CallbackType;
 import org.hibernate.persister.entity.EntityPersister;
 
 /**
- * @author <a href="mailto:kabir.khan@jboss.org">Kabir Khan</a>
+ * @author Kabir Khan
  * @author Steve Ebersole
  */
 public class PostInsertEventListenerStandardImpl implements PostInsertEventListener, CallbackRegistryConsumer {

hibernate-core/src/main/java/org/hibernate/event/spi/PostLoadEvent.java

@@ -11,7 +11,7 @@ import org.hibernate.persister.entity.EntityPersister;
 /**
  * Occurs after an entity instance is fully loaded.
  *
- * @author <a href="mailto:kabir.khan@jboss.org">Kabir Khan</a>, Gavin King
+ * @author Kabir Khan, Gavin King
  */
 public class PostLoadEvent extends AbstractEvent {
 	private Object entity;

hibernate-core/src/main/java/org/hibernate/event/spi/PostLoadEventListener.java

@@ -9,7 +9,7 @@ package org.hibernate.event.spi;
 /**
  * Occurs after an entity instance is fully loaded.
  *
- * @author <a href="mailto:kabir.khan@jboss.org">Kabir Khan</a>
+ * @author Kabir Khan
  */
 public interface PostLoadEventListener {
 	void onPostLoad(PostLoadEvent event);

hibernate-core/src/main/java/org/hibernate/graph/AttributeNode.java

@@ -14,7 +14,7 @@ import org.hibernate.metamodel.model.domain.PersistentAttribute;
 /**
  * Hibernate extension to the JPA entity-graph AttributeNode contract.
  *
- * @author <a href="mailto:stliu@hibernate.org">Strong Liu</a>
+ * @author Strong Liu
  * @author Steve Ebersole
  * @author Andrea Boriero
  */

hibernate-core/src/main/java/org/hibernate/graph/EntityGraphs.java

@@ -23,14 +23,15 @@ import org.hibernate.graph.spi.RootGraphImplementor;
 
 /**
  * A collection of {@link EntityGraph} utilities.
- * These methods really belong inside other classes that we cannot modify, hence here.
+ *
+ * @apiNote These methods really belong inside other classes that we cannot modify.
  * 
  * @author asusnjar
  */
 public final class EntityGraphs {
 	/**
-	 * Merges multiple entity graphs into a single graph that specifies the fetching/loading of all attributes the input
+	 * Merges multiple entity graphs into a single graph that specifies the
-	 * graphs specify.
+	 * fetching/loading of all attributes the input graphs specify.
 	 * 
 	 * @param <T>      Root entity type of the query and graph.
 	 * 
@@ -70,8 +71,8 @@ public final class EntityGraphs {
 	}
 
 	/**
-	 * Convenience method for {@linkplain Query#getResultList() executing} the Query, applying the
+	 * Convenience method for {@linkplain Query#getResultList() executing the query},
-	 * given EntityGraph using the specified semantic
+	 * applying the given {@link EntityGraph} using the specified semantic
 	 *
 	 * @param query The JPA Query
 	 * @param graph The graph to apply
@@ -85,15 +86,16 @@ public final class EntityGraphs {
 	}
 
 	/**
-	 * Form of {@link #executeList(Query, EntityGraph, GraphSemantic)} accepting a TypedQuery.
+	 * Form of {@link #executeList(Query, EntityGraph, GraphSemantic)} accepting a
+	 * {@link TypedQuery}.
 	 *
 	 * @param query The JPA Query
 	 * @param graph The graph to apply
 	 * @param semantic The semantic to use when applying the graph
 	 *
-	 * @apiNote This signature assumes that the Query's return is an entity and that the graph
+	 * @apiNote This signature assumes that the Query's return is an entity and that
-	 * applies to that entity's type.  JPA does not necessarily require that, but it is by
+	 *          the graph applies to that entity's type. JPA does not necessarily
-	 * far the most common usage.
+	 *          require that, but it is by far the most common usage.
 	 */
 	@SuppressWarnings({"unused", "unchecked"})
 	public static <R> List<R> executeList(TypedQuery<R> query, EntityGraph<R> graph, GraphSemantic semantic) {
@@ -101,9 +103,9 @@ public final class EntityGraphs {
 	}
 
 	/**
-	 * Convenience method for {@linkplain Query#getResultList() executing} the Query, applying the
+	 * Convenience method for {@linkplain Query#getResultList() executing the query},
-	 * given EntityGraph using the named semantic using JPA's "hint name" - see
+	 * applying the given {@link EntityGraph} using the named semantic using JPA's
-	 * {@link GraphSemantic#fromHintName}
+	 * "hint name". See {@link GraphSemantic#fromHintName}.
 	 *
 	 * @param query The JPA Query
 	 * @param graph The graph to apply
@@ -119,15 +121,16 @@ public final class EntityGraphs {
 	}
 
 	/**
-	 * Form of {@link #executeList(Query, EntityGraph, String)} accepting a TypedQuery
+	 * Form of {@link #executeList(Query, EntityGraph, String)} accepting a
+	 * {@link TypedQuery}.
 	 *
 	 * @param query The JPA Query
 	 * @param graph The graph to apply
 	 * @param semanticJpaHintName See {@link GraphSemantic#fromHintName}
 	 *
-	 * @apiNote This signature assumes that the Query's return is an entity and that the graph
+	 * @apiNote This signature assumes that the Query's return is an entity and that
-	 * applies to that entity's type.  JPA does not necessarily require that, but it is by
+	 *          the graph applies to that entity's type. JPA does not necessarily
-	 * far the most common usage.
+	 *          require that, but it is by far the most common usage.
 	 */
 	@SuppressWarnings({"unused", "unchecked"})
 	public static <R> List<R> executeList(TypedQuery<R> query, EntityGraph<R> graph, String semanticJpaHintName) {
@@ -135,16 +138,16 @@ public final class EntityGraphs {
 	}
 
 	/**
-	 * Convenience method for {@linkplain Query#getResultList() executing} the Query using the
+	 * Convenience method for {@linkplain Query#getResultList() executing the query}
-	 * given EntityGraph
+	 * using the given {@link EntityGraph}.
 	 *
 	 * @param query The JPA Query
 	 * @param graph The graph to apply
 	 *
-	 * @apiNote operates on the assumption that the "default" semantic for an
+	 * @apiNote Operates on the assumption that the "default" semantic for an
-	 * entity graph applied to a Query is {@link GraphSemantic#FETCH}.  This is simply
+	 *          entity graph applied to a query is {@link GraphSemantic#FETCH}.
-	 * knowledge from JPA EG discussions, nothing that is specifically mentioned or
+	 *          This is simply knowledge from JPA EG discussions, nothing that
-	 * discussed in the spec.
+	 *          is specifically mentioned or discussed in the spec.
 	 */
 	@SuppressWarnings({"unused", "unchecked"})
 	public static List executeList(Query query, EntityGraph graph) {
@@ -154,14 +157,15 @@ public final class EntityGraphs {
 	}
 
 	/**
-	 * Form of {@link #executeList(Query, EntityGraph, String)} accepting a TypedQuery
+	 * Form of {@link #executeList(Query, EntityGraph, String)} accepting a
+	 * {@link TypedQuery}.
 	 *
 	 * @param query The JPA Query
 	 * @param graph The graph to apply
 	 *
-	 * @apiNote This signature assumes that the Query's return is an entity and that the graph
+	 * @apiNote This signature assumes that the Query's return is an entity and that
-	 * applies to that entity's type.  JPA does not necessarily require that, but it is by
+	 *          the graph applies to that entity's type. JPA does not necessarily
-	 * far the most common usage.
+	 *          require that, but it is by far the most common usage.
 	 */
 	@SuppressWarnings("unused")
 	public static <R> List<R> executeList(TypedQuery<R> query, EntityGraph<R> graph) {
@@ -172,9 +176,9 @@ public final class EntityGraphs {
 	//		but really, I think unwrapping as Hibernate's Query and using our
 	//		"proprietary" methods is better (this class is "proprietary" too).
 
-
 	/**
-	 * Compares two entity graphs and returns {@code true} if they are equal, ignoring attribute order.
+	 * Compares two entity graphs and returns {@code true} if they are equal,
+	 * ignoring attribute order.
 	 * 
 	 * @param <T>  Root entity type of BOTH graphs.
 	 * @param a    Graph to compare.
@@ -213,8 +217,8 @@ public final class EntityGraphs {
 	}
 
 	/**
-	 * Compares two entity graph attribute node and returns {@code true} if they are equal, ignoring subgraph attribute
+	 * Compares two entity graph attribute node and returns {@code true} if they are equal,
-	 * order.
+	 * ignoring subgraph attribute order.
 	 */
 	public static boolean areEqual(AttributeNode<?> a, AttributeNode<?> b) {
 		if ( a == b ) {
@@ -232,7 +236,8 @@ public final class EntityGraphs {
 	}
 
 	/**
-	 * Compares two entity subgraph maps and returns {@code true} if they are equal, ignoring order.
+	 * Compares two entity subgraph maps and returns {@code true} if they are equal,
+	 * ignoring order.
 	 */
 	public static boolean areEqual(@SuppressWarnings("rawtypes") Map<Class, Subgraph> a, @SuppressWarnings("rawtypes") Map<Class, Subgraph> b) {
 		if ( a == b ) {
@@ -264,7 +269,8 @@ public final class EntityGraphs {
 	}
 
 	/**
-	 * Compares two entity subgraphs and returns {@code true} if they are equal, ignoring attribute order.
+	 * Compares two entity subgraphs and returns {@code true} if they are equal,
+	 * ignoring attribute order.
 	 */
 	public static boolean areEqual(@SuppressWarnings("rawtypes") Subgraph a, @SuppressWarnings("rawtypes") Subgraph b) {
 		if ( a == b ) {

hibernate-core/src/main/java/org/hibernate/graph/Graph.java

@@ -14,30 +14,33 @@ import org.hibernate.metamodel.model.domain.PersistentAttribute;
 /**
  * A container for {@link AttributeNode} references.
  * <p>
- * Acts as a "bridge" between JPA's {@link jakarta.persistence.EntityGraph} and {@link jakarta.persistence.Subgraph}
+ * Acts as a "bridge" between JPA's {@link jakarta.persistence.EntityGraph}
+ * and {@link jakarta.persistence.Subgraph}.
  *
- * @author <a href="mailto:stliu@hibernate.org">Strong Liu</a>
+ * @author Strong Liu
  * @author Steve Ebersole
  * @author Andrea Boriero
  */
 @SuppressWarnings({"unused", "UnusedReturnValue"})
 public interface Graph<J> extends GraphNode<J> {
 	/**
-	 * Graphs apply only to ManagedTypes.  Returns the ManagedType being graphed here.
+	 * Graphs apply only to {@link jakarta.persistence.metamodel.ManagedType}s.
+	 *
+	 * @return the {@code ManagedType} being graphed here.
 	 */
 	ManagedDomainType<J> getGraphedType();
 
 	/**
-	 * Create a named (if passed `name` != null) root Graph.  The `mutable`
+	 * Create a named root {@link Graph} if the given name is not null.
-	 * parameter controls whether the created Graph is mutable.
 	 *
-	 * @throws CannotBecomeEntityGraphException For named attributes
+	 * @param mutable controls whether the resulting {@code Graph} is mutable
-	 * that are not entity valued
+	 *
+	 * @throws CannotBecomeEntityGraphException If the named attribute is not entity-valued
 	 */
 	RootGraph<J> makeRootGraph(String name, boolean mutable) throws CannotBecomeEntityGraphException;
 
 	/**
-	 * Create a (mutable/immutable) SubGraph based on this Graph
+	 * Create a (mutable or immutable) {@link SubGraph} rooted at this {@link Graph}.
 	 */
 	SubGraph<J> makeSubGraph(boolean mutable);
 

hibernate-core/src/main/java/org/hibernate/graph/GraphNode.java

@@ -7,8 +7,7 @@
 package org.hibernate.graph;
 
 /**
- * Commonality between {@link AttributeNode} and
+ * Commonality between {@link AttributeNode} and {@link Graph}.
- * {@link Graph}.
  *
  * @author Steve Ebersole
  */

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

@@ -8,7 +8,7 @@
 /**
  * Implements and extends the JPA-defined {@linkplain jakarta.persistence.EntityGraph entity graph} API.
  *
- * @apiNote This entire package (including sub-packages) is considered incubating
+ * @apiNote This entire package, including its subpackages, is considered incubating.
  */
 @Incubating
 package org.hibernate.graph;

hibernate-core/src/main/java/org/hibernate/graph/spi/AttributeNodeImplementor.java

@@ -17,7 +17,7 @@ import org.hibernate.metamodel.model.domain.ManagedDomainType;
 /**
  * Integration version of the AttributeNode contract
  *
- * @author <a href="mailto:stliu@hibernate.org">Strong Liu</a>
+ * @author Strong Liu
  * @author Steve Ebersole
  */
 public interface AttributeNodeImplementor<J> extends AttributeNode<J>, GraphNodeImplementor<J> {

hibernate-core/src/main/java/org/hibernate/graph/spi/GraphImplementor.java

@@ -20,7 +20,7 @@ import org.hibernate.metamodel.model.domain.PersistentAttribute;
 /**
  * Integration version of the Graph contract
  *
- * @author <a href="mailto:stliu@hibernate.org">Strong Liu</a>
+ * @author Strong Liu
  * @author Steve Ebersole
  * @author Andrea Boriero
  */

hibernate-core/src/main/java/org/hibernate/graph/spi/GraphNodeImplementor.java

@@ -12,7 +12,7 @@ import org.hibernate.graph.GraphNode;
  * Integration version of the GraphNode contract
  *
  * @author Steve Ebersole
- * @author <a href="mailto:stliu@hibernate.org">Strong Liu</a>
+ * @author Strong Liu
  */
 public interface GraphNodeImplementor<J> extends GraphNode<J> {
 	@Override

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

@@ -6,7 +6,7 @@
  */
 
 /**
- * Enhanced/improved versions of table and sequence based identifier generators targeting portability and unified
+ * Enhanced/improved versions of table and sequence based identifier generators
- * configuration
+ * targeting portability and unified configuration.
  */
 package org.hibernate.id.enhanced;

hibernate-core/src/main/java/org/hibernate/internal/util/SerializationHelper.java

@@ -22,8 +22,8 @@ import org.hibernate.internal.CoreMessageLogger;
 import org.hibernate.type.SerializationException;
 
 /**
- * <p>Assists with the serialization process and performs additional functionality based
+ * Assists with the serialization process and performs additional
- * on serialization.</p>
+ * functionality based on serialization.
  * <p>
  * <ul>
  * <li>Deep clone using serialization
@@ -31,12 +31,11 @@ import org.hibernate.type.SerializationException;
  * <li>Deserialize managing finally and IOException
  * </ul>
  * <p>
- * <p>This class throws exceptions for invalid <code>null</code> inputs.
+ * This class throws exceptions for invalid {@code null} inputs.
- * Each method documents its behaviour in more detail.</p>
  *
- * @author <a href="mailto:nissim@nksystems.com">Nissim Karpenstein</a>
+ * @author Nissim Karpenstein
- * @author <a href="mailto:janekdb@yahoo.co.uk">Janek Bogucki</a>
+ * @author Janek Bogucki
- * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
+ * @author Daniel Rall
  * @author Stephen Colebourne
  * @author Jeff Varszegi
  * @author Gary Gregory
@@ -53,15 +52,15 @@ public final class SerializationHelper {
 	//-----------------------------------------------------------------------
 
 	/**
-	 * <p>Deep clone an <code>Object</code> using serialization.</p>
+	 * Deep clone an object using serialization.
 	 * <p>
-	 * <p>This is many times slower than writing clone methods by hand
+	 * This is many times slower than writing clone methods by hand
 	 * on all objects in your object graph. However, for complex object
 	 * graphs, or for those that don't support deep cloning this can
 	 * be a simple alternative implementation. Of course all the objects
-	 * must be <code>Serializable</code>.</p>
+	 * must be {@code Serializable}.
 	 *
-	 * @param object the <code>Serializable</code> object to clone
+	 * @param object the {@code Serializable} object to clone
 	 *
 	 * @return the cloned object
 	 *
@@ -79,19 +78,19 @@ public final class SerializationHelper {
 	//-----------------------------------------------------------------------
 
 	/**
-	 * <p>Serializes an <code>Object</code> to the specified stream.</p>
+	 * <p>Serializes an object to the given stream.
 	 * <p>
-	 * <p>The stream will be closed once the object is written.
+	 * The stream will be closed once the object is written.
-	 * This avoids the need for a finally clause, and maybe also exception
+	 * This avoids the need for a finally clause, and maybe also
-	 * handling, in the application code.</p>
+	 * for exception handling, in the application code.
 	 * <p>
-	 * <p>The stream passed in is not buffered internally within this method.
+	 * The stream passed in is not buffered internally within this
-	 * This is the responsibility of your application if desired.</p>
+	 * method. This is the responsibility of the caller, if desired.
 	 *
 	 * @param obj the object to serialize to bytes, may be null
 	 * @param outputStream the stream to write to, must not be null
 	 *
-	 * @throws IllegalArgumentException if <code>outputStream</code> is <code>null</code>
+	 * @throws IllegalArgumentException if {@code outputStream} is null
 	 * @throws SerializationException (runtime) if the serialization fails
 	 */
 	public static void serialize(Serializable obj, OutputStream outputStream) throws SerializationException {
@@ -130,8 +129,8 @@ public final class SerializationHelper {
 	}
 
 	/**
-	 * <p>Serializes an <code>Object</code> to a byte array for
+	 * Serializes an object to a byte array for storage or
-	 * storage/serialization.</p>
+	 * externalization.
 	 *
 	 * @param obj the object to serialize to bytes
 	 *
@@ -149,8 +148,8 @@ public final class SerializationHelper {
 	//-----------------------------------------------------------------------
 
 	/**
-	 * Deserializes an object from the specified stream using the Thread Context
+	 * Deserializes an object from the given stream using the
-	 * ClassLoader (TCCL).
+	 * Thread Context ClassLoader (TCCL).
 	 * <p>
 	 * Delegates to {@link #doDeserialize}
 	 *
@@ -158,7 +157,7 @@ public final class SerializationHelper {
 	 *
 	 * @return the deserialized object
 	 *
-	 * @throws IllegalArgumentException if <code>inputStream</code> is <code>null</code>
+	 * @throws IllegalArgumentException if {@code inputStream} is null
 	 * @throws SerializationException (runtime) if the serialization fails
 	 */
 	public static <T> T deserialize(InputStream inputStream) throws SerializationException {
@@ -179,16 +178,16 @@ public final class SerializationHelper {
 	}
 
 	/**
-	 * Deserializes an object from the specified stream using the Thread Context
+	 * Deserializes an object from the given stream using the
-	 * ClassLoader (TCCL).  If there is no TCCL set, the classloader of the calling
+	 * Thread Context ClassLoader (TCCL). If there is no TCCL set,
-	 * class is used.
+	 * the classloader of the calling class is used.
 	 * <p>
-	 * The stream will be closed once the object is read. This avoids the need
+	 * The stream will be closed once the object is read. This
-	 * for a finally clause, and maybe also exception handling, in the application
+	 * avoids the need for a finally clause, and maybe also for
-	 * code.
+	 * exception handling, in the application code.
 	 * <p>
-	 * The stream passed in is not buffered internally within this method.  This is
+	 * The stream passed in is not buffered internally within this
-	 * the responsibility of the caller, if desired.
+	 * method. This is the responsibility of the caller, if desired.
 	 *
 	 * @param inputStream the serialized object input stream, must not be null
 	 * @param loader The classloader to use
@@ -245,9 +244,9 @@ public final class SerializationHelper {
 	}
 
 	/**
-	 * Deserializes an object from an array of bytes using the Thread Context
+	 * Deserializes an object from an array of bytes using the
-	 * ClassLoader (TCCL).  If there is no TCCL set, the classloader of the calling
+	 * Thread Context ClassLoader (TCCL). If there is no TCCL set,
-	 * class is used.
+	 * the classloader of the calling class is used.
 	 * <p>
 	 * Delegates to {@link #deserialize(byte[], ClassLoader)}
 	 *
@@ -290,10 +289,10 @@ public final class SerializationHelper {
 
 	/**
 	 * By default, to resolve the classes being deserialized JDK serialization uses the
-	 * classes loader which loaded the class which initiated the deserialization call.  Here
+	 * classes loader which loaded the class which initiated the deserialization call. Here
-	 * that would be hibernate classes.  However, there are cases where that is not the correct
+	 * that would be Hibernate classes. However, there are cases where that is not the correct
 	 * class loader to use; mainly here we are worried about deserializing user classes in
-	 * environments (app servers, etc) where Hibernate is on a parent classes loader.  To
+	 * environments (app servers, etc) where Hibernate is on a parent classes loader. To
 	 * facilitate for that we allow passing in the class loader we should use.
 	 */
 	private static final class CustomObjectInputStream extends ObjectInputStream {
@@ -312,9 +311,6 @@ public final class SerializationHelper {
 			this.loader3 = loader3;
 		}
 
-		/**
-		 * {@inheritDoc}
-		 */
 		@Override
 		protected Class resolveClass(ObjectStreamClass v) throws IOException, ClassNotFoundException {
 			final String className = v.getName();

hibernate-core/src/main/java/org/hibernate/jdbc/ReturningWork.java

@@ -10,9 +10,13 @@ import java.sql.Connection;
 import java.sql.SQLException;
 
 /**
- * A discrete piece of work following the lines of {@link Work} but returning a result.
+ * A discrete piece of work making use of a {@linkplain Connection JDBC connection}
+ * and returning a result.
  *
  * @author Steve Ebersole
+ *
+ * @see Work
+ * @see org.hibernate.SharedSessionContract#doReturningWork(ReturningWork)
  */
 @FunctionalInterface
 public interface ReturningWork<T> {

hibernate-core/src/main/java/org/hibernate/jdbc/Work.java

@@ -10,9 +10,12 @@ import java.sql.Connection;
 import java.sql.SQLException;
 
 /**
- * Contract for performing a discrete piece of JDBC work.
+ * A discrete piece of work making use of a {@linkplain Connection JDBC connection}.
  *
  * @author Steve Ebersole
+ *
+ * @see ReturningWork
+ * @see org.hibernate.SharedSessionContract#doWork(Work)
  */
 @FunctionalInterface
 public interface Work {

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

@@ -6,10 +6,15 @@
  */
 
 /**
- * Abstracts certain very specific aspects of the low-level interaction between Hibernate
+ * Defines the notion of a unit of JDBC work that may be executed by the session
- * and JDBC.
+ * at the request of the client.
  * <p>
- * Defines {@link org.hibernate.jdbc.Work}, {@link org.hibernate.jdbc.ReturningWork} and
+ * Execution of a unit of work may be requested by calling
- * {@link org.hibernate.jdbc.Expectation}, along with some exceptions
+ * {@link org.hibernate.SharedSessionContract#doWork(org.hibernate.jdbc.Work)} or
+ * {@link org.hibernate.SharedSessionContract#doReturningWork(org.hibernate.jdbc.ReturningWork)}.
+ *
+ * @see org.hibernate.jdbc.Work
+ * @see org.hibernate.jdbc.ReturningWork
+ * @see org.hibernate.jdbc.Expectation
  */
 package org.hibernate.jdbc;

hibernate-core/src/main/java/org/hibernate/jpa/event/internal/CallbackRegistryImpl.java

@@ -20,7 +20,7 @@ import org.hibernate.jpa.event.spi.CallbackType;
 /**
  * Keep track of all lifecycle callbacks and listeners for a given persistence unit
  *
- * @author <a href="mailto:kabir.khan@jboss.org">Kabir Khan</a>
+ * @author Kabir Khan
  * @author Steve Ebersole
  * @author Sanne Grinovero
  */

hibernate-core/src/main/java/org/hibernate/jpa/event/internal/EntityCallback.java

@@ -17,7 +17,7 @@ import org.hibernate.resource.beans.spi.ManagedBeanRegistry;
 /**
  * Represents a JPA callback on the entity itself
  *
- * @author <a href="mailto:kabir.khan@jboss.org">Kabir Khan</a>
+ * @author Kabir Khan
  * @author Steve Ebersole
  */
 final class EntityCallback extends AbstractCallback {

hibernate-core/src/main/java/org/hibernate/jpa/event/internal/ListenerCallback.java

@@ -18,7 +18,7 @@ import org.hibernate.resource.beans.spi.ManagedBeanRegistry;
 /**
  * Represents a JPA callback using a dedicated listener
  *
- * @author <a href="mailto:kabir.khan@jboss.org">Kabir Khan</a>
+ * @author Kabir Khan
  * @author Steve Ebersole
  */
 class ListenerCallback extends AbstractCallback {

hibernate-core/src/main/java/org/hibernate/jpa/event/spi/Callback.java

@@ -15,7 +15,7 @@ import java.io.Serializable;
  * or an annotated method on a separate "listener" class.  This contract presents
  * a unified abstraction for both cases
  *
- * @author <a href="mailto:kabir.khan@jboss.org">Kabir Khan</a>
+ * @author Kabir Khan
  * @author Steve Ebersole
  */
 public interface Callback extends Serializable {

hibernate-core/src/main/java/org/hibernate/metamodel/mapping/ModelPart.java

@@ -21,8 +21,8 @@ import org.hibernate.type.descriptor.java.JavaType;
 
 /**
  * Base descriptor, within the mapping model, for any part of the
- * application's domain model - an attribute,
+ * application's domain model: an attribute, an entity identifier,
- * an entity identifier, collection elements, etc
+ * collection elements, and so on.
  *
  * @see DomainResultProducer
  * @see jakarta.persistence.metamodel.Bindable

hibernate-core/src/main/java/org/hibernate/proxy/HibernateProxy.java

@@ -7,21 +7,25 @@
 package org.hibernate.proxy;
 import java.io.Serializable;
 
+import org.hibernate.Internal;
 import org.hibernate.engine.spi.PrimeAmongSecondarySupertypes;
 
 /**
- * Marker interface for entity proxies
+ * Interface implemented directly by entity proxies, exposing
+ * access to the associated {@link LazyInitializer}.
  *
  * @author Gavin King
  */
 public interface HibernateProxy extends Serializable, PrimeAmongSecondarySupertypes {
 
 	/**
-	 * Extract the LazyInitializer from the object, if
+	 * Extract the {@link LazyInitializer} from the given object,
-	 * and only if the object is actually an HibernateProxy.
+	 * if and only if the object is actually a proxy. Otherwise,
-	 * If not, null is returned.
+	 * return a null value.
-	 * @param object any entity
+	 *
-	 * @return either null (if object is not an HibernateProxy) or the LazyInitializer of the HibernateProxy.
+	 * @param object any reference to an entity
+	 * @return the associated {@link LazyInitializer} if the given
+	 *         object is a proxy, or {@code null} otherwise.
 	 */
 	static LazyInitializer extractLazyInitializer(final Object object) {
 		if ( object instanceof PrimeAmongSecondarySupertypes ) {
@@ -42,17 +46,21 @@ public interface HibernateProxy extends Serializable, PrimeAmongSecondarySuperty
 	Object writeReplace();
 
 	/**
-	 * Get the underlying lazy initialization handler.
+	 * Get the {@linkplain LazyInitializer lazy initialization handler}
+	 * for this object.
 	 *
-	 * @return The lazy initializer.
+	 * @return The associated {@link LazyInitializer}.
 	 */
 	LazyInitializer getHibernateLazyInitializer();
 
 	/**
-	 * Special internal contract to optimize type checking
+	 * Special internal contract to optimize type checking.
+	 *
 	 * @see PrimeAmongSecondarySupertypes
-	 * @return this same instance
+	 *
+	 * @return this instance
 	 */
+	@Internal
 	@Override
 	default HibernateProxy asHibernateProxy() {
 		return this;

hibernate-core/src/main/java/org/hibernate/proxy/LazyInitializer.java

@@ -10,7 +10,7 @@ import org.hibernate.HibernateException;
 import org.hibernate.engine.spi.SharedSessionContractImplementor;
 
 /**
- * Handles fetching of the underlying entity for a proxy
+ * Handles fetching of the underlying entity for a proxy.
  *
  * @author Gavin King
  * @author Steve Ebersole
@@ -20,6 +20,8 @@ public interface LazyInitializer {
 	 * Initialize the proxy, fetching the target entity if necessary.
 	 *
 	 * @throws HibernateException Indicates a problem initializing the proxy.
+	 *
+	 * @see org.hibernate.Hibernate#initialize(Object)
 	 */
 	void initialize() throws HibernateException;
 
@@ -33,8 +35,9 @@ public interface LazyInitializer {
 	}
 
 	/**
-	 * Retrieve the identifier value for the entity our owning proxy represents.
+	 * Retrieve the identifier value for the entity our owning proxy represents,
-	 *
+	 * without initializing the proxy.
+	 * <p>
 	 * When JPA proxy compliance is enabled the proxy is initialized.
 	 *
 	 * @return The identifier value.
@@ -66,6 +69,8 @@ public interface LazyInitializer {
 	 * Is the proxy uninitialized?
 	 *
 	 * @return True if uninitialized; false otherwise.
+	 *
+	 * @see org.hibernate.Hibernate#isInitialized(Object)
 	 */
 	boolean isUninitialized();
 
@@ -104,10 +109,10 @@ public interface LazyInitializer {
 
 	/**
 	 * Is the proxy read-only?
-	 *
+	 * <p>
 	 * The read-only/modifiable setting is not available when the proxy is
 	 * detached or its associated session is closed.
-	 *
+	 * <p>
 	 * To check if the read-only/modifiable setting is available:
 	 *
 	 * @return true, if this proxy is read-only; false, otherwise
@@ -126,7 +131,7 @@ public interface LazyInitializer {
 	 * proxy is initialized, its implementation will have the same read-only/
 	 * modifiable setting as the proxy. In read-only mode, no snapshot is
 	 * maintained and the instance is never dirty checked.
-	 *
+	 * <p>
 	 * If the associated proxy already has the specified read-only/modifiable
 	 * setting, then this method does nothing.
 	 *

hibernate-core/src/main/java/org/hibernate/proxy/ProxyFactory.java

@@ -14,7 +14,7 @@ import org.hibernate.engine.spi.SharedSessionContractImplementor;
 import org.hibernate.type.CompositeType;
 
 /**
- * Contract for run-time, proxy-based lazy initialization proxies.
+ * Contract for runtime, proxy-based lazy initialization proxies.
  *
  * @author Gavin King
  */

hibernate-core/src/main/java/org/hibernate/proxy/map/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>.
+ */
+
+/**
+ * Proxies for entity objects represented as Java {@linkplain java.util.Map maps}.
+ */
+package org.hibernate.proxy.map;

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

@@ -7,6 +7,7 @@
 
 /**
  * This package defines a framework for lazy-initializing entity proxies.
+ * <p>
  * The interfaces here and all their implementations belong to an SPI.
  * They are not part of the public API of Hibernate, and are not meant to
  * be used directly by typical programs which use Hibernate for persistence.

hibernate-core/src/main/java/org/hibernate/proxy/pojo/BasicLazyInitializer.java

@@ -14,7 +14,7 @@ import org.hibernate.proxy.AbstractLazyInitializer;
 import org.hibernate.type.CompositeType;
 
 /**
- * Lazy initializer for POJOs
+ * Lazy initializer for plain Java objects.
  *
  * @author Gavin King
  */

hibernate-core/src/main/java/org/hibernate/proxy/pojo/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>.
+ */
+
+/**
+ * Proxies for plain Java objects.
+ */
+package org.hibernate.proxy.pojo;

hibernate-core/src/main/java/org/hibernate/query/hql/internal/DomainPathPart.java

@@ -13,7 +13,7 @@ import org.hibernate.query.sqm.tree.domain.SqmPath;
 import org.hibernate.query.sqm.tree.expression.SqmExpression;
 
 /**
- * Specialized "intermediate" SemanticPathPart for processing domain model paths
+ * Specialized "intermediate" SemanticPathPart for processing domain model paths/
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/query/hql/internal/HqlParseTreeBuilder.java

@@ -17,7 +17,7 @@ import org.antlr.v4.runtime.CommonTokenStream;
 import org.antlr.v4.runtime.Token;
 
 /**
- * Leverages Antlr to build a parse tree from an HQL query
+ * Leverages ANTLR to build a parse tree from an HQL query.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/query/hql/internal/QualifiedJoinPathConsumer.java

@@ -30,7 +30,7 @@ import org.hibernate.query.sqm.tree.from.SqmRoot;
 import org.jboss.logging.Logger;
 
 /**
- * Specialized "intermediate" SemanticPathPart for processing domain model paths
+ * Specialized "intermediate" SemanticPathPart for processing domain model paths.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/query/hql/internal/QualifiedJoinPredicatePathConsumer.java

@@ -24,7 +24,7 @@ import org.hibernate.query.sqm.tree.select.SqmSubQuery;
 
 /**
  * Specialized consumer for processing domain model paths occurring as part
- * of a join predicate
+ * of a join predicate.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/query/hql/internal/SemanticQueryBuilder.java

@@ -245,7 +245,7 @@ import static org.hibernate.type.spi.TypeConfiguration.isJdbcTemporalType;
 
 /**
  * Responsible for producing an SQM using visitation over an HQL parse tree generated by
- * Antlr via {@link HqlParseTreeBuilder}.
+ * ANTLR via {@link HqlParseTreeBuilder}.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/query/hql/internal/StandardHqlTranslator.java

@@ -33,7 +33,7 @@ import org.antlr.v4.runtime.dfa.DFA;
 import org.antlr.v4.runtime.misc.ParseCancellationException;
 
 /**
- * Standard implementation of SemanticQueryInterpreter
+ * Standard implementation of {@link HqlTranslator}.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/query/hql/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 SPIs for HQL support.
+ */
+package org.hibernate.query.hql.internal;

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

@@ -6,11 +6,30 @@
  */
 
 /**
- * Package defining support for HQL queries (including supprt for JPQL
+ * Package defining support for HQL, including JPQL as a subset of HQL.
- * as a subset of HQL).
  * <p>
- * This includes transformation via Antlr, {@link org.hibernate.query.Query}
+ * Concerns handled by subpackages include:
- * manipulation and execution
+ * <ul>
+ * <li>query language transformation via ANTLR, and
+ * <li>query execution via an instance of {@link org.hibernate.query.Query}.
+ * </ul>
+ * <p>
+ * Translation of HQL to SQL involves the following steps:
+ * <ul>
+ * <li>First, the ANTLR-generated
+ *     {@link org.hibernate.grammars.hql.HqlLexer tokenizer} and
+ *     {@link org.hibernate.grammars.hql.HqlParser parser} work
+ *     in series to parse the text of the query and produce an AST.
+ * <li>Next, {@link org.hibernate.query.hql.internal.SemanticQueryBuilder}
+ *     translates the AST into an instance of the SQM (Semantic Query
+ *     Model) defined in {@link org.hibernate.query.sqm}.
+ * <li>Next, {@link org.hibernate.query.sqm.sql.internal.StandardSqmTranslator}
+ *     transforms the SQM tree and produces a SQL AST, an instance of
+ *     the syntax tree defined by {@link org.hibernate.sql.ast.tree}.
+ * <li>Finally, a SQL dialect-specific implementation of
+ *     {@link org.hibernate.sql.ast.SqlAstTranslator} produces an
+ *     executable SQL statement.
+ * </ul>
  *
  * @see org.hibernate.query.hql.HqlTranslator
  * @see org.hibernate.query.hql.spi.SqmQueryImplementor

hibernate-core/src/main/java/org/hibernate/query/hql/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
+ */
+
+/**
+ * SPIs for HQL support.
+ */
+package org.hibernate.query.hql.spi;

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

@@ -0,0 +1,16 @@
+/*
+ * 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 SQL functions in the SQM model.
+ *
+ * @see org.hibernate.query.sqm.function.SqmFunctionDescriptor
+ */
+@Incubating
+package org.hibernate.query.procedure;
+
+import org.hibernate.Incubating;

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

@@ -7,8 +7,8 @@
 
 /**
  * Support for immutable result/fetch builder graph nodes built from static sources
- * such as JPA's {@link jakarta.persistence.SqlResultSetMapping} or `hbm.xml` mapping
+ * such as {@link jakarta.persistence.SqlResultSetMapping} or the {@code hbm.xml}
- * {@code <resultset/>}.
+ * mapping element {@code <resultset/>}.
  * <p>
  * The differentiation from {@link org.hibernate.query.results.dynamic} is that here
  * we have up-front knowledge of the complete mapping graph and can perform optimized

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

@@ -6,18 +6,20 @@
  */
 
 /**
- * Support for defining result-set mappings used in {@link org.hibernate.query.NativeQuery}
+ * Support for defining result set mappings used in {@link org.hibernate.query.NativeQuery},
- * and {@link org.hibernate.procedure.ProcedureCall} / {@link jakarta.persistence.StoredProcedureQuery}.
+ * {@link org.hibernate.procedure.ProcedureCall}, and {@link jakarta.persistence.StoredProcedureQuery}.
- * These result-set mappings are used to map the values in the JDBC {@link java.sql.ResultSet}
+ * These result set mappings are used to map the values in the JDBC {@link java.sql.ResultSet} into
- * into the query result graph.
+ * the query result graph.
  * <p>
- * Handling the different sources of results and fetches is split into multiple packages and
+ * Subpackages handle different sources of result set mappings:
- * multiple impls for performance reasons. The classes in {@link org.hibernate.query.results.complete}
+ * <ul>
- * represent result/fetch definitions that are completely known up-front and are faster to
+ * <li>{@link org.hibernate.query.results.complete} handles result set mappings which are completely
- * resolve. The definitions in {@link org.hibernate.query.results.dynamic} are built incrementally
+ *     known upfront and are faster to resolve.
- * via Hibernate's {@link org.hibernate.query.NativeQuery} contract need to resolve themselves
+ * <li>{@link org.hibernate.query.results.dynamic} handles result set mappings which are defined
- * against other dynamic result/fetch definitions and therefore take more resources to resolve.
+ *     incrementally via the {@link org.hibernate.query.NativeQuery} interface and need to resolve
- * The classes in {@link org.hibernate.query.results.implicit} represent results that are implied.
+ *     themselves against other dynamic mappings. These take more resources to resolve.
+ * <li>{@link org.hibernate.query.results.implicit} handles implicit result set mappings.
+ * </ul>
  *
  * @see org.hibernate.query.results.ResultSetMapping
  *

hibernate-core/src/main/java/org/hibernate/query/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
+ */
+
+/**
+ * Implementation of the SPIs for native SQL query support.
+ */
+package org.hibernate.query.sql.internal;

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

@@ -6,7 +6,7 @@
  */
 
 /**
- * Package defining support for native SQL queries
+ * Package defining support for native SQL queries.
  *
  * @see org.hibernate.query.NativeQuery
  * @see org.hibernate.query.sql.spi.NativeQueryImplementor

hibernate-core/src/main/java/org/hibernate/query/sql/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
+ */
+
+/**
+ * SPIs for native SQL query support.
+ */
+package org.hibernate.query.sql.spi;