explain how to get things in the javadoc

hibernate-core/src/main/java/org/hibernate/boot/Metadata.java

@@ -30,9 +30,12 @@ import org.hibernate.query.sqm.function.SqmFunctionDescriptor;
 
 /**
  * Represents the ORM model as determined from all provided mapping sources.
+ * An instance may be obtained by calling {@link MetadataSources#buildMetadata()}.
  *
- * NOTE : for the time being this is essentially a copy of the legacy Mappings contract, split between
+ * @apiNote For the time being this is essentially a copy of the legacy
- * reading the mapping information exposed here and collecting it via InFlightMetadataCollector
+ * {@link Mapping} contract, split between reading the mapping information
+ * exposed here and collecting it via
+ * {@link org.hibernate.boot.spi.InFlightMetadataCollector}.
  *
  * @author Steve Ebersole
  *

hibernate-core/src/main/java/org/hibernate/boot/MetadataSources.java

@@ -42,9 +42,14 @@ import org.w3c.dom.Document;
  * Entry point for working with sources of O/R mapping metadata, either
  * in the form of annotated classes, or as XML mapping documents.
  * <p>
- * A client must register sources and then call {@link #buildMetadata()},
+ * An instance of {@code MetadataSources} may be obtained simply by
+ * instantiation, using {@link #MetadataSources() new MetadataSources()}.
+ * The client must register sources and then call {@link #buildMetadata()},
  * or use {@link #getMetadataBuilder()} to customize how the sources are
- * processed (naming strategies, etc).
+ * processed (by registering naming strategies, etc).
+ * <p>
+ * As an alternative to working directly with {@code MetadataSources}, and
+ * {@link Metadata}, a program may use {@link org.hibernate.cfg.Configuration}.
  *
  * @author Steve Ebersole
  *
@@ -66,12 +71,15 @@ public class MetadataSources implements Serializable {
 
 	private Map<String,Class<?>> extraQueryImports;
 
+	/**
+	 * Create a new instance, using a default {@link BootstrapServiceRegistry}.
+	 */
 	public MetadataSources() {
 		this( new BootstrapServiceRegistryBuilder().build() );
 	}
 
 	/**
-	 * Create a metadata sources using the specified service registry.
+	 * Create a new instance using the given {@link ServiceRegistry}.
 	 *
 	 * @param serviceRegistry The service registry to use.
 	 */
@@ -103,7 +111,7 @@ public class MetadataSources implements Serializable {
 
 	protected static boolean isExpectedServiceRegistryType(ServiceRegistry serviceRegistry) {
 		return serviceRegistry instanceof BootstrapServiceRegistry
-				|| serviceRegistry instanceof StandardServiceRegistry;
+			|| serviceRegistry instanceof StandardServiceRegistry;
 	}
 
 	public XmlMappingBinderAccess getXmlMappingBinderAccess() {
@@ -226,7 +234,7 @@ public class MetadataSources implements Serializable {
 	}
 
 	/**
-	 * Var-arg form of {@link #addAnnotatedClass}
+	 * Vararg form of {@link #addAnnotatedClass(Class)}.
 	 */
 	public MetadataSources addAnnotatedClasses(Class<?>... annotatedClasses) {
 		if ( annotatedClasses != null && annotatedClasses.length > 0 ) {
@@ -257,7 +265,7 @@ public class MetadataSources implements Serializable {
 	}
 
 	/**
-	 * Var-arg form of {@link #addAnnotatedClassName}
+	 * Vararg form of {@link #addAnnotatedClassName(String)}.
 	 */
 	public MetadataSources addAnnotatedClassNames(String... annotatedClassNames) {
 		if ( annotatedClassNames != null && annotatedClassNames.length > 0 ) {
@@ -566,9 +574,10 @@ public class MetadataSources implements Serializable {
 	}
 
 	/**
-	 * Read all mappings from a jar file.
+	 * Read all {@code .hbm.xml} mappings from a jar file.
 	 * <p/>
 	 * Assumes that any file named {@code *.hbm.xml} is a mapping document.
+	 * This method does not support {@code orm.xml} files!
 	 *
 	 * @param jar a jar file
 	 *
@@ -591,9 +600,10 @@ public class MetadataSources implements Serializable {
 	}
 
 	/**
-	 * Read all mapping documents from a directory tree.
+	 * Read all {@code .hbm.xml} mapping documents from a directory tree.
 	 * <p/>
 	 * Assumes that any file named {@code *.hbm.xml} is a mapping document.
+	 * This method does not support {@code orm.xml} files!
 	 *
 	 * @param dir The directory
 	 *

hibernate-core/src/main/java/org/hibernate/boot/registry/BootstrapServiceRegistry.java

@@ -9,9 +9,14 @@ package org.hibernate.boot.registry;
 import org.hibernate.service.ServiceRegistry;
 
 /**
- * Provides the most basic services needed.  Class loading, etc.
+ * Provides the most basic services such as class loading. Other
- *
+ * configuration-time objects such as {@link org.hibernate.boot.MetadataSources},
- * Specialized mainly for type safety.
+ * {@link StandardServiceRegistryBuilder}, and {@link org.hibernate.cfg.Configuration}
+ * all depend on an instance of {@code BootstrapServiceRegistry}.
+ * <p>
+ * An instance may be obtained using {@link BootstrapServiceRegistryBuilder#build()}.
+ * <p>
+ * Specialized from {@link ServiceRegistry} mainly for type safety.
  *
  * @see BootstrapServiceRegistryBuilder
  *

hibernate-core/src/main/java/org/hibernate/boot/registry/BootstrapServiceRegistryBuilder.java

@@ -24,10 +24,17 @@ import org.hibernate.integrator.spi.Integrator;
 import org.hibernate.service.ServiceRegistry;
 
 /**
- * Builder for {@link BootstrapServiceRegistry} instances.  Provides registry for services needed for
+ * Builder for {@link BootstrapServiceRegistry} instances.
- * most operations.  This includes {@link Integrator} handling and ClassLoader handling.
+ * <p>
- *
+ * An instance of this class may be obtained by instantiations, simply by
- * Additionally responsible for building and managing the {@link org.hibernate.boot.registry.selector.spi.StrategySelector}
+ * calling {@code new BootstrapServiceRegistryBuilder()}. Then a new
+ * {@code BootstrapServiceRegistry} may be obtained by calling {@link #build()}.
+ * It should be later destroyed by calling {@link #destroy(ServiceRegistry)}.
+ * <p>
+ * Provides a registry of services needed for most operations.
+ * Manages a {@link ClassLoaderService}, a set of {@link Integrator}s, and a
+ * {@link StrategySelectorBuilder} responsible for creation and management
+ * of {@link org.hibernate.boot.registry.selector.spi.StrategySelector}s.
  *
  * @author Steve Ebersole
  * @author Brett Meyer
@@ -39,7 +46,7 @@ public class BootstrapServiceRegistryBuilder {
 
 	private List<ClassLoader> providedClassLoaders;
 	private ClassLoaderService providedClassLoaderService;
-	private StrategySelectorBuilder strategySelectorBuilder = new StrategySelectorBuilder();
+	private final StrategySelectorBuilder strategySelectorBuilder = new StrategySelectorBuilder();
 	private TcclLookupPrecedence tcclLookupPrecedence = TcclLookupPrecedence.AFTER;
 
 	private boolean autoCloseRegistry = true;
@@ -105,7 +112,6 @@ public class BootstrapServiceRegistryBuilder {
 	 *
 	 * @see org.hibernate.boot.registry.selector.spi.StrategySelector#registerStrategyImplementor(Class, String, Class)
 	 */
-	@SuppressWarnings( {"UnusedDeclaration"})
 	public <T> BootstrapServiceRegistryBuilder applyStrategySelector(Class<T> strategy, String name, Class<? extends T> implementation) {
 		this.strategySelectorBuilder.addExplicitStrategyRegistration( strategy, implementation, name );
 		return this;
@@ -120,9 +126,8 @@ public class BootstrapServiceRegistryBuilder {
 	 *
 	 * @see org.hibernate.boot.registry.selector.spi.StrategySelector#registerStrategyImplementor(Class, String, Class)
 	 */
-	@SuppressWarnings( {"UnusedDeclaration"})
 	public BootstrapServiceRegistryBuilder applyStrategySelectors(StrategyRegistrationProvider strategyRegistrationProvider) {
-		for ( StrategyRegistration strategyRegistration : strategyRegistrationProvider.getStrategyRegistrations() ) {
+		for ( StrategyRegistration<?> strategyRegistration : strategyRegistrationProvider.getStrategyRegistrations() ) {
 			this.strategySelectorBuilder.addExplicitStrategyRegistration( strategyRegistration );
 		}
 		return this;

hibernate-core/src/main/java/org/hibernate/boot/registry/StandardServiceRegistry.java

@@ -10,6 +10,8 @@ import org.hibernate.service.ServiceRegistry;
 
 /**
  * Specialization of the {@link ServiceRegistry} contract mainly for type safety.
+ * <p>
+ * An instance may be obtained using {@link StandardServiceRegistryBuilder#build()}.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/boot/registry/StandardServiceRegistryBuilder.java

@@ -377,7 +377,7 @@ public class StandardServiceRegistryBuilder {
 	}
 
 	/**
-	 * Build and resturn the {@link StandardServiceRegistry}.
+	 * Build and return the {@link StandardServiceRegistry}.
 	 *
 	 * @return A newly-instantiated {@link StandardServiceRegistry}
 	 */

hibernate-core/src/main/java/org/hibernate/boot/registry/selector/internal/StrategySelectorBuilder.java

@@ -41,14 +41,14 @@ import org.hibernate.type.JsonBJsonFormatMapper;
 import org.jboss.logging.Logger;
 
 /**
- * Builder for StrategySelector instances.
+ * Builder for {@link StrategySelector} instances.
  *
  * @author Steve Ebersole
  */
 public class StrategySelectorBuilder {
 	private static final Logger log = Logger.getLogger( StrategySelectorBuilder.class );
 
-	private final List<StrategyRegistration> explicitStrategyRegistrations = new ArrayList<>();
+	private final List<StrategyRegistration<?>> explicitStrategyRegistrations = new ArrayList<>();
 
 	/**
 	 * Adds an explicit (as opposed to discovered) strategy registration.
@@ -59,7 +59,6 @@ public class StrategySelectorBuilder {
 	 * @param <T> The type of the strategy.  Used to make sure that the strategy and implementation are type
 	 * compatible.
 	 */
-	@SuppressWarnings("unchecked")
 	public <T> void addExplicitStrategyRegistration(Class<T> strategy, Class<? extends T> implementation, String name) {
 		addExplicitStrategyRegistration( new SimpleStrategyRegistrationImpl<>( strategy, implementation, name ) );
 	}
@@ -114,20 +113,19 @@ public class StrategySelectorBuilder {
 
 		// apply auto-discovered registrations
 		for ( StrategyRegistrationProvider provider : classLoaderService.loadJavaServices( StrategyRegistrationProvider.class ) ) {
-			for ( StrategyRegistration discoveredStrategyRegistration : provider.getStrategyRegistrations() ) {
+			for ( StrategyRegistration<?> discoveredStrategyRegistration : provider.getStrategyRegistrations() ) {
 				applyFromStrategyRegistration( strategySelector, discoveredStrategyRegistration );
 			}
 		}
 
 		// apply customizations
-		for ( StrategyRegistration explicitStrategyRegistration : explicitStrategyRegistrations ) {
+		for ( StrategyRegistration<?> explicitStrategyRegistration : explicitStrategyRegistrations ) {
 			applyFromStrategyRegistration( strategySelector, explicitStrategyRegistration );
 		}
 
 		return strategySelector;
 	}
 
-	@SuppressWarnings("unchecked")
 	private <T> void applyFromStrategyRegistration(StrategySelectorImpl strategySelector, StrategyRegistration<T> strategyRegistration) {
 		for ( String name : strategyRegistration.getSelectorNames() ) {
 			strategySelector.registerStrategyImplementor(

hibernate-core/src/main/java/org/hibernate/cfg/Configuration.java

@@ -64,6 +64,9 @@ import org.hibernate.usertype.UserType;
  * using {@link MetadataBuilder} and {@link StandardServiceRegistryBuilder}
  * under the covers.
  * <p>
+ * An instance of {@code Configuration} may be obtained simply by
+ * instantiation, using {@link #Configuration() new Configuration()}.
+ * <p>
  * A {@code Configuration} may be used to aggregate:
  * <ul>
  * <li>{@linkplain #setProperty(String, String) configuration properties}
@@ -73,12 +76,16 @@ import org.hibernate.usertype.UserType;
  * </ul>
  * In addition, there are convenience methods for adding
  * {@link #addAttributeConverter attribute converters},
- * {@link #registerTypeContributor type contributors}, and
+ * {@link #registerTypeContributor type contributors},
- * {@link #addSqlFunction SQL function descriptors}, for setting
+ * {@link #addSqlFunction SQL function descriptors}, and
- * {@link #setImplicitNamingStrategy naming strategies} and
+ * {@link #addAuxiliaryDatabaseObject auxiliary database objects}, for
- * {@link #setCurrentTenantIdentifierResolver tenant id resolvers},
+ * setting {@link #setImplicitNamingStrategy naming strategies} and a
+ * {@link #setCurrentTenantIdentifierResolver tenant id resolver},
  * and more.
  * <p>
+ * Finally, an instance of {@link SessionFactoryBuilder} is obtained by
+ * calling {@link #buildSessionFactory()}.
+ * <p>
  * Ultimately, this class simply delegates to {@link MetadataBuilder} and
  * {@link StandardServiceRegistryBuilder} to actually do the hard work of
  * {@linkplain #buildSessionFactory() building} the {@code SessionFactory}.
@@ -125,10 +132,20 @@ public class Configuration {
 	private Properties properties;
 	private SharedCacheMode sharedCacheMode;
 
+	/**
+	 * Create a new instance, using a default {@link BootstrapServiceRegistry}
+	 * and a newly instantiated {@link MetadataSources}.
+	 * <p>
+	 * This is the usual method of obtaining a {@code Configuration}.
+	 */
 	public Configuration() {
 		this( new BootstrapServiceRegistryBuilder().build() );
 	}
 
+	/**
+	 * Create a new instance, using the given {@link BootstrapServiceRegistry}
+	 * and a newly instantiated {@link MetadataSources}.
+	 */
 	public Configuration(BootstrapServiceRegistry serviceRegistry) {
 		this.bootstrapServiceRegistry = serviceRegistry;
 		this.metadataSources = new MetadataSources( serviceRegistry );
@@ -136,6 +153,10 @@ public class Configuration {
 		reset();
 	}
 
+	/**
+	 * Create a new instance, using the given {@link MetadataSources}, and a
+	 * {@link BootstrapServiceRegistry} obtained from the {@link MetadataSources}.
+	 */
 	public Configuration(MetadataSources metadataSources) {
 		this.bootstrapServiceRegistry = getBootstrapRegistry( metadataSources.getServiceRegistry() );
 		this.metadataSources = metadataSources;
@@ -540,9 +561,10 @@ public class Configuration {
 	}
 
 	/**
-	 * Read all mappings from a {@code .jar} file.
+	 * Read all {@code .hbm.xml} mappings from a {@code .jar} file.
 	 * <p/>
 	 * Assumes that any file named {@code *.hbm.xml} is a mapping document.
+	 * This method does not support {@code orm.xml} files!
 	 *
 	 * @param jar a jar file
 	 * @return this (for method chaining purposes)
@@ -555,9 +577,10 @@ public class Configuration {
 	}
 
 	/**
-	 * Read all mapping documents from a directory tree.
+	 * Read all {@code .hbm.xml} mapping documents from a directory tree.
 	 * <p/>
 	 * Assumes that any file named {@code *.hbm.xml} is a mapping document.
+	 * This method does not support {@code orm.xml} files!
 	 *
 	 * @param dir The directory
 	 * @return this (for method chaining purposes)

hibernate-core/src/main/java/org/hibernate/service/ServiceRegistry.java

@@ -7,7 +7,22 @@
 package org.hibernate.service;
 
 /**
- * A registry of {@linkplain Service services}.
+ * A registry of {@linkplain Service services}. This interface abstracts
+ * the operations of:
+ * <ul>
+ * <li>{@linkplain org.hibernate.boot.registry.BootstrapServiceRegistry
+ * bootstrap service registries}, which may be obtained from a
+ * {@link org.hibernate.boot.registry.BootstrapServiceRegistryBuilder},
+ * and
+ * <li>{@linkplain org.hibernate.boot.registry.StandardServiceRegistry
+ * standard service registries}, which may be obtained from a
+ * {@link org.hibernate.boot.registry.StandardServiceRegistryBuilder},
+ * </ul>
+ *
+ * @see org.hibernate.boot.registry.BootstrapServiceRegistry
+ * @see org.hibernate.boot.registry.StandardServiceRegistry
+ * @see org.hibernate.boot.registry.BootstrapServiceRegistryBuilder
+ * @see org.hibernate.boot.registry.StandardServiceRegistryBuilder
  *
  * @author Steve Ebersole
  */