work on the jdoc about type annotations

hibernate-core/src/main/java/org/hibernate/annotations/CompositeTypeRegistration.java

@@ -33,6 +33,13 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Retention( RUNTIME )
 @Repeatable( CompositeTypeRegistrations.class )
 public @interface CompositeTypeRegistration {
+	/**
+	 * The embeddable type described by the {@link #userType}.
+	 */
 	Class<?> embeddableClass();
+
+	/**
+	 * The {@link CompositeUserType}.
+	 */
 	Class<? extends CompositeUserType<?>> userType();
 }

hibernate-core/src/main/java/org/hibernate/annotations/JavaTypeRegistration.java

@@ -19,17 +19,21 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Registers the BasicJavaType to use for the given {@link #javaType}
+ * Registers a {@link BasicJavaType} as the default Java type descriptor 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
+ * that class; it will also affect all future processing. However, it will not change
+ * previous resolutions to use this newly registered one. Due to this nondeterminism,
  * it is recommended to only apply registrations to packages or to use a
  * {@link org.hibernate.boot.model.TypeContributor}.
  *
+ * @implNote {@link BasicJavaType} registrations are maintained by the
+ *           {@link org.hibernate.type.descriptor.java.spi.JavaTypeRegistry}.
+ *
  * @since 6.0
  */
 @Target({PACKAGE, TYPE, ANNOTATION_TYPE})

hibernate-core/src/main/java/org/hibernate/annotations/JdbcTypeRegistration.java

@@ -12,26 +12,33 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
 import org.hibernate.type.descriptor.jdbc.JdbcType;
-import org.hibernate.type.descriptor.jdbc.spi.JdbcTypeRegistry;
 
 import static java.lang.annotation.ElementType.PACKAGE;
 import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Describes a SqlTypeDescriptor to be added to the {@link JdbcTypeRegistry}
+ * Registers a {@link JdbcType} as the default JDBC type descriptor for a certain
+ * {@linkplain org.hibernate.type.SqlTypes type code}. The type code is determined by:
+ * <ol>
+ * <li>{@link #registrationCode}, if specified, or
+ * <li>{@link JdbcType#getJdbcTypeCode()}.
+ * </ol>
  * <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
+ * that class; it will also affect all future processing. However, it will not change
+ * previous resolutions to use this newly registered one. Due to this nondeterminism,
  * 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
  *
+ * @implNote {@link JdbcType} registrations are maintained by the
+ *           {@link org.hibernate.type.descriptor.jdbc.spi.JdbcTypeRegistry}.
+ *
  * @since 6.0
  */
 @Target({PACKAGE, TYPE})

hibernate-core/src/main/java/org/hibernate/annotations/TypeRegistration.java

@@ -19,7 +19,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
  * Registers a custom {@linkplain UserType user type} implementation
- * to be used by default for all references to a particular basic type.
+ * to be used by default for all references to a particular class of
+ * {@linkplain jakarta.persistence.Basic basic type}.
  * <p>
  * May be overridden for a specific entity field or property using
  * {@link Type @Type}.
@@ -36,6 +37,13 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Retention( RUNTIME )
 @Repeatable( TypeRegistrations.class )
 public @interface TypeRegistration {
+	/**
+	 * The basic type described by the {@link #userType}.
+	 */
 	Class<?> basicClass();
+
+	/**
+	 * The {@link UserType}.
+	 */
 	Class<? extends UserType<?>> userType();
 }

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

@@ -122,6 +122,10 @@
  *         <li>{@link org.hibernate.annotations.Nationalized}
  *         </ul>
  *     <li><p>
+ *         Furthermore, a {@link org.hibernate.annotations.JavaTypeRegistration} or
+ *         {@link org.hibernate.annotations.JdbcTypeRegistration} allows the choice
+ *         of {@code JavaType} or {@code JdbcType} to be made <em>implicitly</em>.
+ *     <li><p>
  *         A compositional type mapping also comes with a
  *         {@link org.hibernate.type.descriptor.java.MutabilityPlan}, which is usually
  *         chosen by the {@code JavaType}, but which may be overridden using the
@@ -133,12 +137,15 @@
  *     all come in specialized flavors for handling map keys, list indexes, and so on.
  * <li><p>
  *     Alternatively, a program may implement the {@link org.hibernate.usertype.UserType}
- *     interface and associate it with a field or property explicitly using the
- *     {@link org.hibernate.annotations.Type @Type} annotation, or implicitly using the
- *     {@link org.hibernate.annotations.TypeRegistration @TypeRegistration} annotation.
+ *     interface and associate it with a field or property
+ *     <ul>
+ *     <li>explicitly, using the {@link org.hibernate.annotations.Type @Type} annotation,
+ *         or
+ *     <li>implicitly, using the {@link org.hibernate.annotations.TypeRegistration @TypeRegistration}
+ *         annotation.
+ *     </ul>
  *     <p>
  *     There are some specialized flavors of the {@code @Type} annotation too.
- * </li>
  * </ul>
  * <p>
  * These two approaches cannot be used together. A {@code UserType} always takes precedence
@@ -165,6 +172,21 @@
  * See the <em>User Guide</em> or the package {@link org.hibernate.type} for further
  * discussion.
  *
+ * <h3 id="composite-types">Composite types</h3>
+ *
+ * A <em>composite type</em> is a type which maps to multiple columns. An example of a
+ * composite type is an {@linkplain jakarta.persistence.Embeddable embeddable} object,
+ * but this is not the only sort of composite type in Hibernate.
+ * <p>
+ * A program may implement the {@link org.hibernate.usertype.CompositeUserType}
+ * interface and associate it with a field or property:
+ * <ul>
+ * <li>explicitly, using the {@link org.hibernate.annotations.CompositeType @CompositeType}
+ *     annotation, or
+ * <li>implicitly, using the {@link org.hibernate.annotations.CompositeTypeRegistration @CompositeTypeRegistration}
+ *     annotation.
+ * </ul>
+ *
  * <h3 id="second-level-cache">Second level cache</h3>
  * <p>
  * When we make a decision to store an entity in the second-level cache, we must decide