From 0426c152d0828a282fd4c7c6cd3cb241ecb764c7 Mon Sep 17 00:00:00 2001
From: Steve Ebersole <steve@hibernate.org>
Date: Sun, 23 Jan 2022 12:43:02 -0600
Subject: [PATCH] General clean-up of Javadoc for `o.h.annotations` package

---
 .../src/main/java/org/hibernate/annotations/Any.java     | 9 +++++----
 .../java/org/hibernate/annotations/AnyDiscriminator.java | 4 +++-
 .../org/hibernate/annotations/AnyDiscriminatorValue.java | 3 +++
 .../org/hibernate/annotations/AttributeAccessor.java     | 6 +++---
 .../src/main/java/org/hibernate/annotations/Bag.java     | 6 +++++-
 .../hibernate/annotations/EmbeddableInstantiator.java    | 2 +-
 .../annotations/EmbeddableInstantiatorRegistration.java  | 5 ++++-
 .../annotations/EmbeddableInstantiatorRegistrations.java | 2 ++
 .../java/org/hibernate/annotations/GenericGenerator.java | 6 +++++-
 .../org/hibernate/annotations/JavaTypeRegistration.java  | 6 ++----
 .../java/org/hibernate/annotations/JdbcTypeCode.java     | 4 ++--
 .../org/hibernate/annotations/JdbcTypeRegistration.java  | 4 ++--
 .../main/java/org/hibernate/cfg/AvailableSettings.java   | 2 ++
 13 files changed, 39 insertions(+), 20 deletions(-)

diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Any.java b/hibernate-core/src/main/java/org/hibernate/annotations/Any.java
index 73156bc675..ae94d7aff9 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/Any.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/Any.java
@@ -17,17 +17,18 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Maps a discriminated to-one style associations pointing to one of several entity types
+ * Maps a discriminated to-one style association pointing to one of several entity types
  * depending on a local discriminator, as opposed to discriminated inheritance where the
  * discriminator is kept as part of the entity hierarchy (see {@link jakarta.persistence.Inheritance}
  * and {@link jakarta.persistence.InheritanceType#SINGLE_TABLE} for details about discriminated
  * inheritance mappings).
- * <p>
+ * <p/>
  * For example, if you consider an {@code Order} entity containing {@code Payment} information
  * where {@code Payment} might be of type {@code CashPayment} or {@code CreditCardPayment},
  * the {@code @Any} approach would be to keep that discriminator and matching value on the
- * {@code Order} itself. Thought of another way, the "foreign key" is really made up of the
- * value and discriminator.
+ * {@code Order} itself instead as part of the {@code Payment} class. Thought of another way,
+ * the "foreign key" is really made up of the value and discriminator.  Note however that this
+ * composite foreign-key is a conceptual and cannot be phsical.
  * <ul>
  *     <li>Use {@link Column} or {@link Formula} to define the "column" to which the
  *         discriminator is mapped.
diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/AnyDiscriminator.java b/hibernate-core/src/main/java/org/hibernate/annotations/AnyDiscriminator.java
index 3308d6c893..fc00a8441a 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/AnyDiscriminator.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/AnyDiscriminator.java
@@ -19,11 +19,13 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 /**
  * Simplified form for describing the discriminator value mapping as a discrete
  * set.  Follows the pattern of JPA's {@link DiscriminatorColumn#discriminatorType()}.
- *
+ * <p/>
  * Can be used in conjunction with {@link JdbcType} or {@link JdbcTypeCode} to
  * further describe the underlying mapping.  {@link JdbcType} or {@link JdbcTypeCode}
  * can also be used without AnyDiscriminator.
  *
+ * @see Any
+ *
  * @since 6.0
  */
 @java.lang.annotation.Target({METHOD, FIELD, ANNOTATION_TYPE})
diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/AnyDiscriminatorValue.java b/hibernate-core/src/main/java/org/hibernate/annotations/AnyDiscriminatorValue.java
index 8bbee9fbe8..513a1111c6 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/AnyDiscriminatorValue.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/AnyDiscriminatorValue.java
@@ -18,6 +18,9 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * Specifies the mapping for a single any-valued discriminator value
  * to the corresponding entity
  *
+ * @see Any
+ * @see AnyDiscriminator
+ *
  * @since 6.0
  */
 @java.lang.annotation.Target({METHOD, FIELD, ANNOTATION_TYPE})
diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/AttributeAccessor.java b/hibernate-core/src/main/java/org/hibernate/annotations/AttributeAccessor.java
index 0c22760426..fcde8313e7 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/AttributeAccessor.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/AttributeAccessor.java
@@ -18,17 +18,17 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
  * Names a persistent property access strategy ({@link PropertyAccessStrategy}) to use.
- *
+ * <p/>
  * Can be specified at either:<ul>
  *     <li>
- *         <strong>TYPE</strong> level, which will act as naming the default accessor strategy for
+ *         <strong>TYPE</strong> level, which will act as the default accessor strategy for
  *         all attributes on the class which do not explicitly name an accessor strategy
  *     </li>
  *     <li>
  *         <strong>METHOD/FIELD</strong> level, which will be in effect for just that attribute.
  *     </li>
  * </ul>
- *
+ * <p/>
  * Should only be used to name custom {@link PropertyAccessStrategy}.  For
  * {@code property/field} access, the JPA {@link jakarta.persistence.Access} annotation should be preferred
  * using the appropriate {@link jakarta.persistence.AccessType}.  However, if this annotation is used with
diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Bag.java b/hibernate-core/src/main/java/org/hibernate/annotations/Bag.java
index 0878c83dc9..a19c8bbfa2 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/Bag.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/Bag.java
@@ -8,6 +8,8 @@ package org.hibernate.annotations;
 
 import java.lang.annotation.Retention;
 
+import org.hibernate.cfg.AvailableSettings;
+
 import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
 import static java.lang.annotation.ElementType.FIELD;
 import static java.lang.annotation.ElementType.METHOD;
@@ -16,10 +18,12 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 /**
  * Can be used to map a {@link java.util.List}-valued attribute using
  * {@link org.hibernate.metamodel.CollectionClassification#BAG} semantics.
- *
+ * <p/>
  * @apiNote Ignored if either {@link jakarta.persistence.OrderColumn} or
  * {@link ListIndexBase} is used.
  *
+ * @implSpec May also be specified SessionFactory-wide using {@value AvailableSettings#DEFAULT_LIST_SEMANTICS}
+ *
  * @author Steve Ebersole
  */
 @java.lang.annotation.Target({METHOD, FIELD, ANNOTATION_TYPE})
diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/EmbeddableInstantiator.java b/hibernate-core/src/main/java/org/hibernate/annotations/EmbeddableInstantiator.java
index 51b114f16b..0cff061eea 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/EmbeddableInstantiator.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/EmbeddableInstantiator.java
@@ -16,7 +16,7 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Specifies a custom instantiator implementation
+ * Specifies a custom instantiator for a specific embedded
  */
 @Target( {TYPE, FIELD, METHOD, ANNOTATION_TYPE} )
 @Retention( RUNTIME )
diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/EmbeddableInstantiatorRegistration.java b/hibernate-core/src/main/java/org/hibernate/annotations/EmbeddableInstantiatorRegistration.java
index 41060a92cf..1db8a7bfe8 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/EmbeddableInstantiatorRegistration.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/EmbeddableInstantiatorRegistration.java
@@ -18,7 +18,10 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Registers a custom instantiator implementation
+ * Registers a custom instantiator implementation to be used
+ * for all references to a particular {@link jakarta.persistence.Embeddable}.
+ * <p/>
+ * May be overridden for a specific embedded using {@link org.hibernate.annotations.EmbeddableInstantiator}
  */
 @Target( {TYPE, ANNOTATION_TYPE, PACKAGE} )
 @Retention( RUNTIME )
diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/EmbeddableInstantiatorRegistrations.java b/hibernate-core/src/main/java/org/hibernate/annotations/EmbeddableInstantiatorRegistrations.java
index 6ac8b7fdde..28532aaed2 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/EmbeddableInstantiatorRegistrations.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/EmbeddableInstantiatorRegistrations.java
@@ -15,6 +15,8 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
+ * Grouping of {@link EmbeddableInstantiatorRegistration}
+ *
  * @author Steve Ebersole
  */
 @Target( {TYPE, ANNOTATION_TYPE, PACKAGE} )
diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/GenericGenerator.java b/hibernate-core/src/main/java/org/hibernate/annotations/GenericGenerator.java
index b58275c7df..f010775af3 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/GenericGenerator.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/GenericGenerator.java
@@ -16,7 +16,11 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Generator annotation describing any kind of Hibernate generator in a generic (de-typed) manner.
+ * Generator annotation describing any kind of Hibernate generator in a
+ * generic (de-typed) manner.
+ * <p/>
+ * For a more type-safe way to specify generators in annotations, see
+ * {@link IdGeneratorType}
  *
  * @author Emmanuel Bernard
  */
diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/JavaTypeRegistration.java b/hibernate-core/src/main/java/org/hibernate/annotations/JavaTypeRegistration.java
index c8d511f960..4697989815 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/JavaTypeRegistration.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/JavaTypeRegistration.java
@@ -19,18 +19,16 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
  * Registers the BasicJavaType to use for the given {@link #javaType}
- *
+ * <p/>
  * Registrations applied to a package are processed before Hibernate begins to process
  * any attributes, etc.
- *
+ * <p/>
  * Registrations applied to a class are only applied once Hibernate begins to process
  * that class; it will also affect all future processing.  However, it will not change
  * previous resolutions to use this newly registered one.  Because of this randomness
  * it is recommended to only apply registrations to packages or to use a
  * {@link org.hibernate.boot.model.TypeContributor}.
  *
- * @see org.hibernate.boot.model.TypeContributor
- *
  * @since 6.0
  */
 @java.lang.annotation.Target({PACKAGE, TYPE, ANNOTATION_TYPE})
diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/JdbcTypeCode.java b/hibernate-core/src/main/java/org/hibernate/annotations/JdbcTypeCode.java
index 3d0a26850e..7a3d13f0a0 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/JdbcTypeCode.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/JdbcTypeCode.java
@@ -39,11 +39,11 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  *         value.
  *     </li>
  * </ul>
- *
+ * <p/>
  * This code is generally as one of the values defined in {@link java.sql.Types}, but are not
  * limited to these.  The code is resolved against an internal registry of {@link JdbcType}
  * references.  See the user-guide for additional details.
- *
+ * <p/>
  * See <a href="package-summary.html#basic-value-mapping"/> for high-level discussion
  * of basic value mapping.
  *
diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/JdbcTypeRegistration.java b/hibernate-core/src/main/java/org/hibernate/annotations/JdbcTypeRegistration.java
index c77bb616a9..e013f2b219 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/JdbcTypeRegistration.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/JdbcTypeRegistration.java
@@ -19,10 +19,10 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
  * Describes a SqlTypeDescriptor to be added to the {@link JdbcTypeRegistry}
- *
+ * <p/>
  * Registrations applied to a package are processed before Hibernate begins to process
  * any attributes, etc.
- *
+ * <p/>
  * Registrations applied to a class are only applied once Hibernate begins to process
  * that class; it will also affect all future processing.  However, it will not change
  * previous resolutions to use this newly registered one.  Because of this randomness
diff --git a/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java b/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java
index c0fa626036..35f31e343a 100644
--- a/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java
+++ b/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java
@@ -761,6 +761,8 @@ public interface AvailableSettings {
 	 *     <li>the (case insensitive) name of a {@code CollectionClassification}, or
 	 *     <li>a {@link Class} representing either {@link java.util.List} or {@link java.util.Collection}.
 	 * </ul>
+	 * <p/>
+	 * Backwards compatibility can be achieved by specifying `hibernate.mapping.default_list_semantics=bag` e.g.
 	 *
 	 * @see org.hibernate.jpa.spi.JpaCompliance#isJpaListComplianceEnabled()
 	 *