document a couple of limitations

hibernate-core/src/main/java/org/hibernate/boot/model/FunctionContributor.java

@@ -22,6 +22,12 @@ package org.hibernate.boot.model;
  * The most common way to integrate a {@code FunctionContributor} is by making
  * it discoverable via the Java {@link java.util.ServiceLoader} facility.
  *
+ * @apiNote Unfortunately there's currently no programmatic way to register
+ *          an instance with {@code Configuration} or {@code MetadataBuilder}.
+ *          Nor can it be registered via a corresponding setting defined in
+ *          {@link org.hibernate.jpa.boot.spi.JpaSettings}. These are things
+ *          which <em>are</em> possible for its best friend {@link TypeContributor}.
+ *
  * @see org.hibernate.query.sqm.function.SqmFunctionRegistry
  *
  * @author Karel Maesen

hibernate-core/src/main/java/org/hibernate/boot/model/TypeContributor.java

@@ -9,16 +9,21 @@ package org.hibernate.boot.model;
 import org.hibernate.service.ServiceRegistry;
 
 /**
- * On object that contributes custom types and type descriptors, eventually
- * to a {@link org.hibernate.type.spi.TypeConfiguration}, via an instance
- * of {@link TypeContributions}.
- * <p>
+ * On object that contributes custom types and type descriptors, eventually to
+ * a {@link org.hibernate.type.spi.TypeConfiguration}, via an instance of
+ * {@link TypeContributions}.
+ * <ul>
+ * <li>
  *     The most common way to integrate a {@code TypeContributor} is by making
  *     it discoverable via the Java {@link java.util.ServiceLoader} facility.
- * <p>
- * Alternatively, a {@code TypeContributor} may be supplied to
+ * <li>
+ *     Alternatively, a {@code TypeContributor} may be programmatically supplied to
  *     {@link org.hibernate.cfg.Configuration#registerTypeContributor(TypeContributor)}
  *     or even {@link org.hibernate.boot.MetadataBuilder#applyTypes(TypeContributor)}.
+ * <li>
+ *     Finally, in the JPA boostrap process, {@code TypeContributor}s may be
+ *     listed via {@link org.hibernate.jpa.boot.spi.JpaSettings#TYPE_CONTRIBUTORS}.
+ * </ul>
  *
  * @author Steve Ebersole
  *

hibernate-core/src/main/java/org/hibernate/boot/spi/MetadataBuilderContributor.java

@@ -14,13 +14,18 @@ import org.hibernate.boot.MetadataBuilder;
  * In implementation may be registered with the JPA provider using the property
  * {@value org.hibernate.jpa.boot.spi.JpaSettings#METADATA_BUILDER_CONTRIBUTOR}.
  *
+ * @apiNote Currently, this API is only supported in the JPA persistence provider.
+ *          It's unfortunate that implementations are not discoverable like
+ *          {@link org.hibernate.boot.model.TypeContributor} and
+ *          {@link org.hibernate.boot.model.FunctionContributor}.
+ *
  * @author Vlad Mihalcea
  *
  * @since 5.3
  */
 public interface MetadataBuilderContributor {
 	/**
-	 * Perform the process of contributing to MetadataSources.
+	 * Perform the process of contributing to the {@link MetadataBuilder}.
 	 *
 	 * @param metadataBuilder The {@link MetadataBuilder}, to which to contribute.
 	 */