improve Javadoc to types in mapping package

hibernate-core/src/main/java/org/hibernate/mapping/Any.java

@@ -19,7 +19,8 @@ import org.hibernate.type.AnyType;
 import org.hibernate.type.Type;
 
 /**
- * Boot-time descriptor of a polymorphic association to one-of-several tables.
+ * A mapping model object representing a {@linkplain org.hibernate.annotations.Any polymorphic association}
+ * to one of several tables.
  *
  * @author Gavin King
  */

hibernate-core/src/main/java/org/hibernate/mapping/AttributeContainer.java

@@ -7,14 +7,12 @@
 package org.hibernate.mapping;
 
 /**
- * Defines an additional contract for PersistentClass/Join in terms of being able to
- * contain attributes (Property).
- * <p/>
- * NOTE : this unifying contract is only used atm from HBM binding and so only defines the
- * needs of that use-case.
+ * Identifies a mapping model object which may have {@linkplain Property attributes} (fields or properties).
+ * Abstracts over {@link PersistentClass} and {@link Join}.
  *
  * @author Steve Ebersole
  */
+//NOTE: this unifying contract is currently only used from HBM binding and so only defines the needs of that use case.
 public interface AttributeContainer {
 	void addProperty(Property attribute);
 }

hibernate-core/src/main/java/org/hibernate/mapping/Bag.java

@@ -15,7 +15,8 @@ import org.hibernate.type.CollectionType;
 import org.hibernate.usertype.UserCollectionType;
 
 /**
- * A bag permits duplicates, so it has no primary key
+ * A mapping model object representing a collection of type {@link java.util.Collection} which may
+ * contain duplicates. Since a bag permits duplicates, it has no primary key
  * 
  * @author Gavin King
  */

hibernate-core/src/main/java/org/hibernate/mapping/Collection.java

@@ -37,7 +37,7 @@ import org.hibernate.type.Type;
 import org.hibernate.usertype.UserCollectionType;
 
 /**
- * Mapping for a collection. Subclasses specialize to particular collection styles.
+ * A mapping model object representing a collection. Subclasses specialize to particular kinds of collection.
  *
  * @author Gavin King
  */

hibernate-core/src/main/java/org/hibernate/mapping/Column.java

@@ -35,7 +35,8 @@ import org.hibernate.type.spi.TypeConfiguration;
 import static org.hibernate.internal.util.StringHelper.safeInterning;
 
 /**
- * A column of a relational database {@link Table table}.
+ * A mapping model object representing a {@linkplain jakarta.persistence.Column column}
+ * of a relational database {@linkplain Table table}.
  *
  * @author Gavin King
  */

hibernate-core/src/main/java/org/hibernate/mapping/Component.java

@@ -38,7 +38,10 @@ import org.hibernate.type.EmbeddedComponentType;
 import org.hibernate.type.Type;
 
 /**
- * The mapping for an embeddable class.
+ * A mapping model object that represents an {@linkplain jakarta.persistence.Embeddable embeddable class}.
+ * <p>
+ * Note that the name of this class is historical and unfortunate. An embeddable class holds a "component"
+ * of the state of an entity. It has absolutely nothing to do with modularity in software engineering.
  *
  * @author Gavin King
  * @author Steve Ebersole

hibernate-core/src/main/java/org/hibernate/mapping/Constraint.java

@@ -26,7 +26,7 @@ import org.hibernate.engine.spi.Mapping;
 import static org.hibernate.internal.util.StringHelper.isEmpty;
 
 /**
- * A constraint on a relational database table.
+ * A mapping model object representing a constraint on a relational database table.
  *
  * @author Gavin King
  * @author Brett Meyer

hibernate-core/src/main/java/org/hibernate/mapping/DependantValue.java

@@ -11,14 +11,13 @@ import org.hibernate.boot.spi.MetadataBuildingContext;
 import org.hibernate.type.Type;
 
 /**
- * A value which is "typed" by reference to some other
- * value (for example, a foreign key is typed by the
- * referenced primary key).
+ * A mapping model object representing a {@linkplain Value value} which is "typed" by reference
+ * to some other value (for example, a foreign key is typed by the referenced primary key).
  *
  * @author Gavin King
  */
 public class DependantValue extends SimpleValue implements Resolvable, SortableValue {
-	private KeyValue wrappedValue;
+	private final KeyValue wrappedValue;
 	private boolean nullable;
 	private boolean updateable;
 	private boolean sorted;

hibernate-core/src/main/java/org/hibernate/mapping/ForeignKey.java

@@ -16,7 +16,7 @@ import org.hibernate.dialect.Dialect;
 import org.hibernate.internal.util.StringHelper;
 
 /**
- * A foreign key constraint.
+ * A mapping model object representing a {@linkplain jakarta.persistence.ForeignKey foreign key} constraint.
  *
  * @author Gavin King
  */

hibernate-core/src/main/java/org/hibernate/mapping/Formula.java

@@ -19,7 +19,9 @@ import org.hibernate.type.spi.TypeConfiguration;
 import static org.hibernate.internal.util.StringHelper.safeInterning;
 
 /**
- * A formula is a derived column value
+ * A mapping model object representing a SQL {@linkplain org.hibernate.annotations.Formula formula}
+ * which is used as a "derived" {@link Column} in an entity mapping.
+ *
  * @author Gavin King
  */
 public class Formula implements Selectable, Serializable {

hibernate-core/src/main/java/org/hibernate/mapping/IdentifierBag.java

@@ -15,8 +15,7 @@ import org.hibernate.type.IdentifierBagType;
 import org.hibernate.usertype.UserCollectionType;
 
 /**
- * An {@code IdentifierBag} has a primary key consisting of
- * just the identifier column
+ * A bag with a generated (surrogate) key. Its primary key is just the identifier column.
  */
 public class IdentifierBag extends IdentifierCollection {
 

hibernate-core/src/main/java/org/hibernate/mapping/IdentifierCollection.java

@@ -15,7 +15,8 @@ import org.hibernate.resource.beans.spi.ManagedBean;
 import org.hibernate.usertype.UserCollectionType;
 
 /**
- * A collection with a synthetic "identifier" column
+ * A mapping model object representing a collection with a synthetic "identifier" column,
+ * that is, a surrogate key.
  */
 public abstract class IdentifierCollection extends Collection {
 

hibernate-core/src/main/java/org/hibernate/mapping/Index.java

@@ -26,7 +26,7 @@ import static org.hibernate.internal.util.StringHelper.isNotEmpty;
 import static org.hibernate.internal.util.StringHelper.qualify;
 
 /**
- * A relational table index
+ * A mapping model object representing an {@linkplain jakarta.persistence.Index index} on a relational database table.
  *
  * @author Gavin King
  */

hibernate-core/src/main/java/org/hibernate/mapping/Join.java

@@ -15,6 +15,12 @@ import org.hibernate.engine.spi.ExecuteUpdateResultCheckStyle;
 import org.hibernate.sql.Alias;
 
 /**
+ * A mapping model object representing some sort of auxiliary table, for
+ * example, an {@linkplain jakarta.persistence.JoinTable association table},
+ * a {@linkplain jakarta.persistence.SecondaryTable secondary table}, or a
+ * table belonging to a {@linkplain jakarta.persistence.InheritanceType#JOINED
+ * joined subclass}.
+ *
  * @author Gavin King
  */
 public class Join implements AttributeContainer, Serializable {

hibernate-core/src/main/java/org/hibernate/mapping/JoinedSubclass.java

@@ -13,7 +13,10 @@ import org.hibernate.boot.Metadata;
 import org.hibernate.boot.spi.MetadataBuildingContext;
 
 /**
- * A subclass in a table-per-subclass mapping
+ * A mapping model object that represents a subclass in a "joined" or
+ * {@linkplain jakarta.persistence.InheritanceType#JOINED "table per subclass"}
+ * inheritance hierarchy.
+ *
  * @author Gavin King
  */
 public class JoinedSubclass extends Subclass implements TableOwner {

hibernate-core/src/main/java/org/hibernate/mapping/KeyValue.java

@@ -12,9 +12,11 @@ import org.hibernate.id.IdentifierGenerator;
 import org.hibernate.id.factory.IdentifierGeneratorFactory;
 
 /**
- * Represents an identifying key of a table: the value for primary key
- * of an entity, or a foreign key of a collection or join table or
- * joined subclass table.
+ * A mapping model {@link Value} which may be treated as an identifying key of a
+ * relational database table. A {@code KeyValue} might represent the primary key
+ * of an entity or the foreign key of a collection, join table, secondary table,
+ * or joined subclass table.
+ *
  * @author Gavin King
  */
 public interface KeyValue extends Value {

hibernate-core/src/main/java/org/hibernate/mapping/List.java

@@ -16,6 +16,7 @@ import org.hibernate.type.ListType;
 import org.hibernate.usertype.UserCollectionType;
 
 /**
+ * A mapping model object representing a collection of type {@link java.util.List}.
  * A list mapping has a primary key consisting of the key columns + index column.
  *
  * @author Gavin King

hibernate-core/src/main/java/org/hibernate/mapping/ManyToOne.java

@@ -16,7 +16,8 @@ import org.hibernate.type.EntityType;
 import org.hibernate.type.Type;
 
 /**
- * A many-to-one association mapping
+ * A mapping model object representing a {@linkplain jakarta.persistence.ManyToOne many-to-one association}.
+ *
  * @author Gavin King
  */
 public class ManyToOne extends ToOne {

hibernate-core/src/main/java/org/hibernate/mapping/Map.java

@@ -18,8 +18,8 @@ import org.hibernate.type.SortedMapType;
 import org.hibernate.usertype.UserCollectionType;
 
 /**
- * A map has a primary key consisting of
- * the key columns + index columns.
+ * A mapping model object representing a collection of type {@link java.util.Map}.
+ * A map has a primary key consisting of the key columns + index columns.
  */
 public class Map extends IndexedCollection {
 

hibernate-core/src/main/java/org/hibernate/mapping/MappedSuperclass.java

@@ -11,19 +11,9 @@ import java.util.Iterator;
 import java.util.List;
 
 /**
- * Represents a @MappedSuperclass.
- * A @MappedSuperclass can be a superclass of an @Entity (root or not)
- *
- * This class primary goal is to give a representation to @MappedSuperclass
- * in the metamodel in order to reflect them in the JPA 2 metamodel.
- *
- * Do not use outside this use case.
- *
- * 
- * A proper redesign will be evaluated in Hibernate 4
- *
- * Implementation details:
- * properties are copies of their closest sub-persistentClass versions
+ * A mapping model object representing a {@linkplain jakarta.persistence.MappedSuperclass mapped superclass}
+ * of an entity class. A mapped superclass is not itself an entity, but it may declare persistent
+ * attributes which are inherited by entity subclasses.
  *
  * @author Emmanuel Bernard
  */

hibernate-core/src/main/java/org/hibernate/mapping/OneToMany.java

@@ -20,7 +20,7 @@ import org.hibernate.type.EntityType;
 import org.hibernate.type.Type;
 
 /**
- * A mapping for a one-to-many association
+ * A mapping model object representing a {@linkplain jakarta.persistence.OneToMany many-to-one association}.
  *
  * @author Gavin King
  */

hibernate-core/src/main/java/org/hibernate/mapping/OneToOne.java

@@ -17,7 +17,8 @@ import org.hibernate.type.ForeignKeyDirection;
 import org.hibernate.type.Type;
 
 /**
- * A one-to-one association mapping
+ * A mapping model object representing a {@linkplain jakarta.persistence.OneToOne many-to-one association}.
+ *
  * @author Gavin King
  */
 public class OneToOne extends ToOne {

hibernate-core/src/main/java/org/hibernate/mapping/PersistentClass.java

@@ -38,7 +38,7 @@ import org.hibernate.sql.Alias;
 import org.hibernate.type.Type;
 
 /**
- * The mapping for an entity.
+ * A mapping model object that represents an {@linkplain jakarta.persistence.Entity entity class}.
  *
  * @author Gavin King
  */

hibernate-core/src/main/java/org/hibernate/mapping/PrimaryKey.java

@@ -13,7 +13,7 @@ import org.hibernate.internal.util.StringHelper;
 import org.jboss.logging.Logger;
 
 /**
- * A primary key constraint.
+ * A mapping model object representing a primary key constraint.
  *
  * @author Gavin King
  * @author Steve Ebersole

hibernate-core/src/main/java/org/hibernate/mapping/Property.java

@@ -32,7 +32,7 @@ import org.hibernate.type.CompositeType;
 import org.hibernate.type.Type;
 
 /**
- * Represents a property or field of an {@link PersistentClass entity}
+ * A mapping model object representing a property or field of an {@link PersistentClass entity}
  * or {@link Component embeddable class}.
  *
  * @author Gavin King

hibernate-core/src/main/java/org/hibernate/mapping/RelationalModel.java

@@ -10,7 +10,8 @@ import org.hibernate.boot.model.relational.SqlStringGenerationContext;
 import org.hibernate.engine.spi.Mapping;
 
 /**
- * A relational object which may be created using DDL
+ * A mapping model object representing a relational object which may be created using DDL.
+ *
  * @author Gavin King
  *
  * @deprecated not needed anymore.

hibernate-core/src/main/java/org/hibernate/mapping/RootClass.java

@@ -22,7 +22,8 @@ import org.hibernate.internal.util.collections.SingletonIterator;
 import org.hibernate.persister.entity.EntityPersister;
 
 /**
- * The root class of an inheritance hierarchy
+ * A mapping model object that represents the root class in an entity class
+ * {@linkplain jakarta.persistence.Inheritance inheritance} hierarchy.
  *
  * @author Gavin King
  */

hibernate-core/src/main/java/org/hibernate/mapping/Selectable.java

@@ -11,7 +11,7 @@ import org.hibernate.query.sqm.function.SqmFunctionRegistry;
 import org.hibernate.type.spi.TypeConfiguration;
 
 /**
- * Models the commonality between a column and a formula (computed value).
+ * Models the commonality between a {@link Column} and a {@link Formula} (computed value).
  */
 public interface Selectable {
 	/**

hibernate-core/src/main/java/org/hibernate/mapping/Set.java

@@ -19,8 +19,10 @@ import org.hibernate.type.SortedSetType;
 import org.hibernate.usertype.UserCollectionType;
 
 /**
- * A set with no nullable element columns. It will have a primary key
- * consisting of all table columns (ie. key columns + element columns).
+ * A mapping model object representing a collection of type {@link java.util.List}.
+ * A set has no nullable element columns (unless it is a one-to-many association).
+ * It has a primary key consisting of all columns (i.e. key columns + element columns).
+ *
  * @author Gavin King
  */
 public class Set extends Collection {

hibernate-core/src/main/java/org/hibernate/mapping/SimpleValue.java

@@ -66,7 +66,8 @@ import org.hibernate.type.spi.TypeConfiguration;
 import org.hibernate.usertype.DynamicParameterizedType;
 
 /**
- * Any value that maps to columns.
+ * A mapping model object that represents any value that maps to columns.
+ *
  * @author Gavin King
  */
 public abstract class SimpleValue implements KeyValue {

hibernate-core/src/main/java/org/hibernate/mapping/SingleTableSubclass.java

@@ -16,6 +16,10 @@ import org.hibernate.internal.util.collections.JoinedIterator;
 import org.hibernate.internal.util.collections.JoinedList;
 
 /**
+ * A mapping model object that represents a subclass in a
+ * {@linkplain jakarta.persistence.InheritanceType#SINGLE_TABLE single table}
+ * inheritance hierarchy.
+ *
  * @author Gavin King
  */
 public class SingleTableSubclass extends Subclass {

hibernate-core/src/main/java/org/hibernate/mapping/Subclass.java

@@ -21,7 +21,9 @@ import org.hibernate.internal.util.collections.SingletonIterator;
 import org.hibernate.persister.entity.EntityPersister;
 
 /**
- * A subclass in a table-per-class-hierarchy mapping
+ * A mapping model object that represents a subclass in an entity class
+ * {@linkplain jakarta.persistence.Inheritance inheritance} hierarchy.
+ *
  * @author Gavin King
  */
 public class Subclass extends PersistentClass {

hibernate-core/src/main/java/org/hibernate/mapping/Table.java

@@ -38,7 +38,7 @@ import static java.util.Collections.unmodifiableList;
 import static java.util.Collections.unmodifiableMap;
 
 /**
- * A relational database table.
+ * A mapping model object representing a relational database {@linkplain jakarta.persistence.Table table}.
  *
  * @author Gavin King
  */

hibernate-core/src/main/java/org/hibernate/mapping/ToOne.java

@@ -16,7 +16,8 @@ import org.hibernate.internal.util.ReflectHelper;
 import java.util.Objects;
 
 /**
- * A simple-point association (ie. a reference to another entity).
+ * A mapping model object representing an association where the target side has cardinality one.
+ *
  * @author Gavin King
  */
 public abstract class ToOne extends SimpleValue implements Fetchable, SortableValue {

hibernate-core/src/main/java/org/hibernate/mapping/UnionSubclass.java

@@ -11,7 +11,10 @@ import java.util.List;
 import org.hibernate.boot.spi.MetadataBuildingContext;
 
 /**
- * A subclass in a table-per-concrete-class mapping
+ * A mapping model object that represents a subclass in a "union" or
+ * {@linkplain jakarta.persistence.InheritanceType#TABLE_PER_CLASS "table per concrete class"}
+ * inheritance hierarchy.
+ *
  * @author Gavin King
  */
 public class UnionSubclass extends Subclass implements TableOwner {

hibernate-core/src/main/java/org/hibernate/mapping/UniqueKey.java

@@ -14,7 +14,7 @@ import org.hibernate.engine.spi.Mapping;
 import org.hibernate.internal.util.StringHelper;
 
 /**
- * A unique key constraint.
+ * A mapping model object representing a unique key constraint on a relational database table.
  *
  * @author Brett Meyer
  */

hibernate-core/src/main/java/org/hibernate/mapping/Value.java

@@ -17,11 +17,13 @@ import org.hibernate.service.ServiceRegistry;
 import org.hibernate.type.Type;
 
 /**
- * A value is anything that is persisted by value, instead of by
- * reference. It is essentially a Hibernate {@link Type}, together
- * with zero or more columns. Values are wrapped by things with
- * higher level semantics, for example properties, collections,
- * classes.
+ * A mapping model object which represents something that's persisted "by value",
+ * instead of "by reference", that is, anything with no primary key.
+ * <p>
+ * A {@code Value} is essentially a Hibernate {@link Type}, together with zero or
+ * more {@link Column columns}. In the mapping model, a {@code Value} always comes
+ * wrapped in something with higher-level semantics, for example, a property, a
+ * collection, or a class.
  *
  * @author Gavin King
  */

hibernate-core/src/main/java/org/hibernate/mapping/package.html

@@ -9,7 +9,10 @@
 <head></head>
 <body>
 <p>
-	This package defines the Hibernate configuration-time metamodel.
+	This package defines the Hibernate configuration-time mapping model.
+	The objects defined in this package are produced by the annotation
+	binding process, and consumed by the code with builds persisters and
+	loaders. They do not outlive the configuration process.
 </p>
 </body>
 </html>