add a historical note to the jdoc of org.hibernate.usertype

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

@@ -15,7 +15,7 @@
  * importance to application developers, though it remains a very important
  * internal abstraction.
  *
- * <h3>Basic types</h3>
+ * <h3 id="basic">Basic types</h3>
  *
  * For {@linkplain jakarta.persistence.Basic basic} types, we prefer to model the
  * type mapping in terms the combination of:
@@ -59,7 +59,7 @@
  * See {@link org.hibernate.annotations} for information on how to influence basic
  * type mappings using annotations.
  *
- * <h3>Custom types</h3>
+ * <h3 id="custom">Custom types</h3>
  *
  * The package {@link org.hibernate.usertype} provides a way for application developers
  * to define new types without being exposed to the full complexity of the {@code Type}

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

@@ -6,7 +6,8 @@
  */
 
 /**
- * An API for user-defined custom types.
+ * An API for user-defined custom types which extend the set of built-in
+ * {@linkplain org.hibernate.type.Type types} defined in {@link org.hibernate.type}.
  * <p>
  * A custom type might map a {@linkplain org.hibernate.usertype.UserType single column},
  * or it might map {@linkplain org.hibernate.usertype.CompositeUserType multiple columns}.
@@ -14,5 +15,15 @@
  * @see org.hibernate.usertype.UserType
  * @see org.hibernate.usertype.CompositeUserType
  * @see org.hibernate.type
+ *
+ * @apiNote Historically, {@link org.hibernate.usertype.UserType} was the
+ *          most important extension point in Hibernate, and
+ *          {@link org.hibernate.usertype.CompositeUserType} was much less
+ *          popular. But in modern Hibernate, the terrain formerly occupied
+ *          by {@code UserType} has been encroached, first by
+ *          {@link jakarta.persistence.AttributeConverter}, and then by the
+ *          new {@linkplain org.hibernate.type "compositional" approach to
+ *          basic types}. Contrariwise, {@code CompositeUserType} has been
+ *          redesigned and is now more powerful and much easier to use.
  */
 package org.hibernate.usertype;