Javadoc and various improvements to configuration

Author: sebersole

hibernate-models/src/main/java/org/hibernate/models/spi/ModelsConfiguration.java

@@ -6,15 +6,14 @@
 
 import java.util.Collection;
 import java.util.HashMap;
-import java.util.Iterator;
 import java.util.Map;
 
 import org.hibernate.models.internal.BasicModelBuildingContextImpl;
 import org.hibernate.models.internal.ModelsLogging;
 import org.hibernate.models.internal.SimpleClassLoading;
 
 /**
- * Bootstrapping
+ * Bootstrapping of {@linkplain SourceModelBuildingContext}
  *
  * @author Steve Ebersole
  */
@@ -29,38 +28,87 @@ public class ModelsConfiguration {
 	public ModelsConfiguration() {
 	}
 
+	/**
+	 * Configuration values in effect.
+	 *
+	 * @apiNote Configuration settings only have effect with certain
+	 * providers.
+	 */
 	public Map<Object, Object> getConfigValues() {
 		return configValues;
 	}
 
-	public Object configValue(Object key, Object value) {
+	/**
+	 * Provide a {@linkplain #getConfigValues() configuration value}.
+	 */
+	public ModelsConfiguration configValue(Object key, Object value) {
+		setConfigValue( key, value );
+		return this;
+	}
+
+	/**
+	 * Provide a {@linkplain #getConfigValues() configuration value}.
+	 */
+	public Object setConfigValue(Object key, Object value) {
 		return configValues.put( key, value );
 	}
 
+	/**
+	 * {@linkplain ClassLoading} to use.
+	 */
 	public ClassLoading getClassLoading() {
 		return classLoading;
 	}
 
-	public void setClassLoading(ClassLoading classLoading) {
+	/**
+	 * Specify a specific {@linkplain #getClassLoading() ClassLoading} to use.
+	 */
+	public ModelsConfiguration setClassLoading(ClassLoading classLoading) {
 		this.classLoading = classLoading;
+		return this;
 	}
 
+	/**
+	 * A primer for {@linkplain ClassDetailsRegistry} and
+	 * {@linkplain AnnotationDescriptorRegistry} applied when
+	 * the {@linkplain SourceModelBuildingContext} is first built.
+	 */
 	public RegistryPrimer getRegistryPrimer() {
 		return registryPrimer;
 	}
 
-	public void setRegistryPrimer(RegistryPrimer registryPrimer) {
+	/**
+	 * Specify a {@linkplain #getRegistryPrimer() registry primer}.
+	 */
+	public ModelsConfiguration setRegistryPrimer(RegistryPrimer registryPrimer) {
 		this.registryPrimer = registryPrimer;
+		return this;
 	}
 
+	/**
+	 * An {@linkplain SourceModelBuildingContextProvider explicit provider} to use.
+	 *
+	 * @see #setExplicitContextProvider
+	 */
 	public SourceModelBuildingContextProvider getExplicitContextProvider() {
 		return explicitContextProvider;
 	}
 
-	public void setExplicitContextProvider(SourceModelBuildingContextProvider explicitContextProvider) {
+	/**
+	 * Specify an {@linkplain #getExplicitContextProvider explicit provider} for
+	 * {@linkplain SourceModelBuildingContext} instances.
+	 *
+	 * @implNote Prefer use of Java {@linkplain java.util.ServiceLoader service loading}
+	 * for supplying a specific provider.
+	 */
+	public ModelsConfiguration setExplicitContextProvider(SourceModelBuildingContextProvider explicitContextProvider) {
 		this.explicitContextProvider = explicitContextProvider;
+		return this;
 	}
 
+	/**
+	 * Build the {@linkplain SourceModelBuildingContext} instance.
+	 */
 	public SourceModelBuildingContext bootstrap() {
 		if ( explicitContextProvider != null ) {
 			final SourceModelBuildingContext context = explicitContextProvider.produceContext(
@@ -78,9 +126,7 @@ public SourceModelBuildingContext bootstrap() {
 		if ( discoveredProviders.size() > 1 ) {
 			ModelsLogging.MODELS_LOGGER.debugf( "Multiple SourceModelBuildingContextProvider impls found" );
 		}
-		final Iterator<SourceModelBuildingContextProvider> iterator = discoveredProviders.iterator();
-		while ( iterator.hasNext() ) {
-			final SourceModelBuildingContextProvider provider = iterator.next();
+		for ( SourceModelBuildingContextProvider provider : discoveredProviders ) {
 			final SourceModelBuildingContext context = provider.produceContext(
 					classLoading,
 					registryPrimer,