document the boolean converters

hibernate-core/src/main/java/org/hibernate/type/CompositeType.java

@@ -14,8 +14,10 @@ import org.hibernate.engine.spi.CascadeStyle;
 import org.hibernate.engine.spi.SharedSessionContractImplementor;
 
 /**
- * Contract for value types to hold collections and have cascades, etc.  The notion is that of composition.  JPA terms
- * this an embeddable.
+ * Represents a <em>composite</em> type, a type which itself has typed attributes.
+ * <p>
+ * For example, a type representing an {@linkplain jakarta.persistence.Embeddable embeddable}
+ * class is a composite type.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/type/ConvertedBasicType.java

@@ -9,7 +9,8 @@ package org.hibernate.type;
 import org.hibernate.metamodel.model.convert.spi.BasicValueConverter;
 
 /**
- * Extension for BasicType impls which have an implied conversion
+ * Extension for implementations of {@link BasicType} which have an implied
+ * {@linkplain BasicValueConverter conversion}.
  */
 public interface ConvertedBasicType<J> extends BasicType<J> {
 	BasicValueConverter<J,?> getValueConverter();

hibernate-core/src/main/java/org/hibernate/type/NumericBooleanConverter.java

@@ -17,7 +17,7 @@ import jakarta.persistence.Converter;
 import org.hibernate.type.descriptor.jdbc.JdbcType;
 
 /**
- * Handles conversion to/from Boolean as `0` (false) or `1` (true)
+ * Handles conversion to/from {@code Boolean} as {@code 0} (false) or {@code 1} (true)
  *
  * @author Steve Ebersole
  */

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

@@ -8,7 +8,8 @@
 /**
  * A Hibernate {@link org.hibernate.type.Type} is a strategy for mapping a Java
  * property type to a JDBC type or types. Every persistent attribute of an entity
- * or embeddable object has a {@code org.hibernate.type.Type}.
+ * or embeddable object has a {@code Type}, even attributes which represent
+ * associations or hold references to embedded objects.
  * <p>
  * On the other hand, in modern Hibernate, {@code Type} itself is of receding
  * importance to application developers, though it remains a very important
@@ -67,6 +68,23 @@
  *     {@link jakarta.persistence.Embeddable} object mapping.
  * </ul>
  *
+ * <h3>Built-in converters for boolean mappings</h3>
+ *
+ * In older version of Hibernate there were dedicated {@code Type}s mapping Java
+ * {@code boolean} to {@code char(1)} or {@code integer} database columns. These
+ * have now been replaced by the converters:
+ * <ul>
+ * <li>{@link org.hibernate.type.TrueFalseConverter}, which encodes a boolean value
+ *     as {@code 'T'} or {@code 'F'},
+ * <li>{@link org.hibernate.type.YesNoConverter}, which encodes a boolean value
+ *     as {@code 'Y'} or {@code 'N'}, and
+ * <li>{@link org.hibernate.type.NumericBooleanConverter}, which encodes a boolean
+ *     value as {@code 1} or {@code 0}.
+ * </ul>
+ * <p>
+ * These converters may be applied, as usual, using the JPA-defined
+ * {@link jakarta.persistence.Converter} annotation.
+ *
  * @see org.hibernate.type.Type
  * @see org.hibernate.type.SqlTypes
  */