minor edits to the jdoc of o.h.boot.spi package

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

@@ -41,7 +41,7 @@ import org.jboss.jandex.IndexView;
 @Incubating
 public interface BootstrapContext {
 	/**
-	 * The service-registry available to bootstrapping
+	 * The service registry available to bootstrapping
 	 */
 	StandardServiceRegistry getServiceRegistry();
 
@@ -51,6 +51,8 @@ public interface BootstrapContext {
 	MutableJpaCompliance getJpaCompliance();
 
 	/**
+	 * The {@link TypeConfiguration} belonging to this {@code BootstrapContext}.
+	 *
 	 * @see TypeConfiguration
 	 */
 	TypeConfiguration getTypeConfiguration();
@@ -81,11 +83,10 @@ public interface BootstrapContext {
 	boolean isJpaBootstrap();
 
 	/**
-	 *
 	 * Indicates that bootstrap was initiated from JPA bootstrapping.
 	 *
 	 * @implSpec Internally, {@code false} is the assumed value.
-	 *           We only need to call this to mark that as {@code true}.
+	 *           We only need to call this to mark it {@code true}.
 	 */
 	void markAsJpaBootstrap();
 
@@ -94,12 +95,12 @@ public interface BootstrapContext {
 	 * {@link jakarta.persistence.spi.PersistenceUnitInfo#getNewTempClassLoader()},
 	 * if any.
 	 *
-	 * @return The tempo ClassLoader
+	 * @return The temporary {@code ClassLoader}
 	 */
 	ClassLoader getJpaTempClassLoader();
 
 	/**
-	 * Access to class loading capabilities
+	 * Access to class loading capabilities.
 	 */
 	ClassLoaderAccess getClassLoaderAccess();
 
@@ -119,7 +120,7 @@ public interface BootstrapContext {
 	ArchiveDescriptorFactory getArchiveDescriptorFactory();
 
 	/**
-	 * Access to the options to be used for scanning
+	 * Access to the options to be used for scanning.
 	 *
 	 * @return The scan options
 	 */
@@ -135,12 +136,14 @@ public interface BootstrapContext {
 	ScanEnvironment getScanEnvironment();
 
 	/**
-	 * Access to the Scanner to be used for scanning.
+	 * Access to the {@link org.hibernate.boot.archive.scan.spi.Scanner} to be used
+	 * for scanning.
+	 * <p>
 	 * Can be:
 	 * <ul>
-	 *     <li>A Scanner instance</li>
+	 *     <li>An instance of {@link org.hibernate.boot.archive.scan.spi.Scanner},
-	 *     <li>A Class reference to the Scanner implementor</li>
+	 *     <li>a {@code Class} reference to the {@code Scanner} implementor, or
-	 *     <li>A String naming the Scanner implementor</li>
+	 *     <li>a string naming the {@code Scanner} implementor.
 	 * </ul>
 	 *
 	 * @return The scanner
@@ -160,7 +163,7 @@ public interface BootstrapContext {
 	/**
 	 * Access to the Jandex index passed by call to
 	 * {@link org.hibernate.boot.MetadataBuilder#applyIndexView(IndexView)}, if any.
-	 * <p>
+	 *
 	 * @apiNote Jandex is currently not used, see
 	 *          <a href="https://github.com/hibernate/hibernate-orm/wiki/Roadmap7.0">the roadmap</a>
 	 *
@@ -170,8 +173,8 @@ public interface BootstrapContext {
 
 	/**
 	 * Access to any SQL functions explicitly registered with the
-	 * {@code MetadataBuilder}.
+	 * {@link org.hibernate.boot.MetadataBuilder}.
-	 * This does not include {@code Dialect}-defined functions, etc.
+	 * This does not include {@code Dialect}-registered functions.
 	 * <p>
 	 * Should never return {@code null}.
 	 *
@@ -181,7 +184,7 @@ public interface BootstrapContext {
 
 	/**
 	 * Access to any {@link AuxiliaryDatabaseObject}s explicitly registered with
-	 * the {@code MetadataBuilder}.
+	 * the {@link org.hibernate.boot.MetadataBuilder}.
 	 * This does not include {@link AuxiliaryDatabaseObject}s defined in mappings.
 	 * <p>
 	 * Should never return {@code null}.

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

@@ -9,8 +9,8 @@ package org.hibernate.boot.spi;
 import java.net.URL;
 
 /**
- * During the process of building the metamodel, access to the {@link ClassLoader}
+ * During the process of building the metamodel, access to the {@link ClassLoader} is
- * is highly discouraged. However, sometimes it is needed. This contract helps mitigate
+ * strongly discouraged. However, sometimes it is needed. This contract helps mitigate
  * access to the {@link ClassLoader} in these cases.
  *
  * @author Steve Ebersole
@@ -19,20 +19,19 @@ import java.net.URL;
  */
 public interface ClassLoaderAccess {
 	/**
-	 * Obtain a Class reference by name
+	 * Obtain a {@link Class} reference by name
 	 *
-	 * @param name The name of the Class to get a reference to.
+	 * @param name The name of the class
-	 *
+	 * @return The {@code Class} object with the given name
-	 * @return The Class.
 	 */
 	<T> Class<T> classForName(String name);
 
 	/**
 	 * Locate a resource by name
 	 *
-	 * @param resourceName The name of the resource to resolve.
+	 * @param resourceName The name of the resource to resolve
-	 *
+	 * @return The located resource;
-	 * @return The located resource; may return {@code null} to indicate the resource was not found
+	 *         may return {@code null} to indicate the resource was not found
 	 */
 	URL locateResource(String resourceName);
 }

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

@@ -188,7 +188,7 @@ public interface InFlightMetadataCollector extends Mapping, MetadataImplementor
 	 *
 	 * @param typeDefinition The named type definition to add.
 	 *
-	 * @throws DuplicateMappingException If a TypeDefinition already exists with that name.
+	 * @throws DuplicateMappingException If a {@link TypeDefinition} already exists with that name.
 	 *
 	 * @deprecated Use {@link #getTypeDefinitionRegistry()} instead
 	 *
@@ -197,6 +197,10 @@ public interface InFlightMetadataCollector extends Mapping, MetadataImplementor
 	@Deprecated
 	void addTypeDefinition(TypeDefinition typeDefinition);
 
+	/**
+	 * Access to the {@link TypeDefinitionRegistry}, which may be used to add
+	 * type definitions to this metadata repository.
+	 */
 	TypeDefinitionRegistry getTypeDefinitionRegistry();
 
 	/**
@@ -204,7 +208,7 @@ public interface InFlightMetadataCollector extends Mapping, MetadataImplementor
 	 *
 	 * @param definition The filter definition to add.
 	 *
-	 * @throws DuplicateMappingException If a FilterDefinition already exists with that name.
+	 * @throws DuplicateMappingException If a {@link FilterDefinition} already exists with that name.
 	 */
 	void addFilterDefinition(FilterDefinition definition);
 
@@ -215,6 +219,9 @@ public interface InFlightMetadataCollector extends Mapping, MetadataImplementor
 	 */
 	void addAuxiliaryDatabaseObject(AuxiliaryDatabaseObject auxiliaryDatabaseObject);
 
+	/**
+	 * Add a {@link FetchProfile}.
+	 */
 	void addFetchProfile(FetchProfile profile);
 
 	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

@@ -10,7 +10,7 @@ import org.hibernate.boot.SessionFactoryBuilder;
 
 /**
  * An extension point for integrators that wish to hook into the process of how a SessionFactory
- * is built. Intended as a "discoverable service" ({@link java.util.ServiceLoader}).  There can
+ * is built. Intended as a "discoverable service" ({@link java.util.ServiceLoader}). There can
  * be at most one implementation discovered that returns a non-null {@link SessionFactoryBuilder}.
  *
  * @author Steve Ebersole
@@ -20,13 +20,13 @@ public interface SessionFactoryBuilderFactory {
 	 * The contract method. Return the {@link SessionFactoryBuilder}. May return {@code null}
 	 *
 	 * @param metadata The metadata from which we will be building a {@code SessionFactory}.
-	 * @param defaultBuilder The default SessionFactoryBuilder instance.
+	 * @param defaultBuilder The default {@code SessionFactoryBuilder} instance.
 	 *                       If the {@code SessionFactoryBuilder} being built here needs to use
 	 *                       this passed {@code SessionFactoryBuilder} instance, it is the
 	 *                       responsibility of the built {@code SessionFactoryBuilder} impl
 	 *                       to delegate configuration calls to the passed default impl.
 	 *
-	 * @return The SessionFactoryBuilder, or {@code null}
+	 * @return The {@code SessionFactoryBuilder}, or {@code null}
 	 */
 	SessionFactoryBuilder getSessionFactoryBuilder(MetadataImplementor metadata, SessionFactoryBuilderImplementor defaultBuilder);
 }

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

@@ -9,22 +9,29 @@ package org.hibernate.boot.spi;
 import org.hibernate.boot.SessionFactoryBuilder;
 
 /**
- * Additional contract for {@link SessionFactoryBuilder} mainly intended for implementors
+ * Additional SPI contract for {@link SessionFactoryBuilder}, mainly intended for
- * of {@link SessionFactoryBuilderFactory}.
+ * implementors of {@link SessionFactoryBuilderFactory}.
  *
  * @author Steve Ebersole
  */
 public interface SessionFactoryBuilderImplementor extends SessionFactoryBuilder {
 
+	/**
+	 * Called if {@link org.hibernate.cfg.AvailableSettings#ALLOW_JTA_TRANSACTION_ACCESS}
+	 * is not enabled.
+	 */
 	void disableJtaTransactionAccess();
 
+	/**
+	 * Called if {@link org.hibernate.cfg.AvailableSettings#ALLOW_REFRESH_DETACHED_ENTITY}
+	 * is not enabled.
+	 */
 	default void disableRefreshDetachedEntity() {
 	}
 
 	/**
-	 * Build the SessionFactoryOptions that will ultimately be passed to SessionFactoryImpl constructor.
+	 * Build the {@link SessionFactoryOptions} that will ultimately be passed to the
-	 *
+	 * constructor of {@link org.hibernate.internal.SessionFactoryImpl}.
-	 * @return The options.
 	 */
 	SessionFactoryOptions buildSessionFactoryOptions();
 }

hibernate-core/src/main/java/org/hibernate/jpa/boot/internal/EntityManagerFactoryBuilderImpl.java

@@ -89,7 +89,6 @@ import jakarta.persistence.EntityNotFoundException;
 import jakarta.persistence.PersistenceException;
 import jakarta.persistence.spi.PersistenceUnitTransactionType;
 
-import static org.hibernate.cfg.AvailableSettings.ALLOW_REFRESH_DETACHED_ENTITY;
 import static org.hibernate.cfg.AvailableSettings.CFG_XML_FILE;
 import static org.hibernate.cfg.AvailableSettings.CLASSLOADERS;
 import static org.hibernate.cfg.AvailableSettings.CLASS_CACHE_PREFIX;
@@ -1474,7 +1473,7 @@ public class EntityManagerFactoryBuilderImpl implements EntityManagerFactoryBuil
 			( ( SessionFactoryBuilderImplementor ) sfBuilder ).disableJtaTransactionAccess();
 		}
 
-		final boolean allowRefreshDetachedEntity = readBooleanConfigurationValue( ALLOW_REFRESH_DETACHED_ENTITY );
+		final boolean allowRefreshDetachedEntity = readBooleanConfigurationValue( AvailableSettings.ALLOW_REFRESH_DETACHED_ENTITY );
 		if ( !allowRefreshDetachedEntity ) {
 			( (SessionFactoryBuilderImplementor) sfBuilder ).disableRefreshDetachedEntity();
 		}