General clean-up of Javadoc for `o.h.annotations` package

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
+ * {@code Order} itself instead as part of the {@code Payment} class. Thought of another way,
- * value and discriminator.
+ * 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.

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})

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})

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

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})

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 )

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 )

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} )

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
  */

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})

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.
  *

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

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()
 	 *