attempt to make better sense of some of this service-related stuff in…

… the docs

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

@@ -68,7 +68,7 @@ public BootstrapServiceRegistryBuilder applyIntegrator(Integrator integrator) {
 	}
 
 	/**
-	 * Adds a provided {@link ClassLoader} for use in class-loading and resource-lookup.
+	 * Adds a provided {@link ClassLoader} for use in classloading and resource lookup.
 	 *
 	 * @param classLoader The class loader to use
 	 *
@@ -83,7 +83,7 @@ public BootstrapServiceRegistryBuilder applyClassLoader(ClassLoader classLoader)
 	}
 
 	/**
-	 * Defines when the lookup in the thread context {@code ClassLoader} is done
+	 * Defines when the lookup in the thread context {@code ClassLoader} is done.
 	 * 
 	 * @param precedence The lookup precedence
 	 */
@@ -92,7 +92,7 @@ public void applyTcclLookupPrecedence(TcclLookupPrecedence precedence) {
 	}
 
 	/**
-	 * Adds a provided {@link ClassLoaderService} for use in class-loading and resource-lookup.
+	 * Adds a provided {@link ClassLoaderService} for use in classloading and resource lookup.
 	 *
 	 * @param classLoaderService The class loader service to use
 	 *
@@ -109,8 +109,8 @@ public BootstrapServiceRegistryBuilder applyClassLoaderService(ClassLoaderServic
 	 * @param strategy The strategy
 	 * @param name The registered name
 	 * @param implementation The strategy implementation Class
-	 * @param <T> Defines the strategy type and makes sure that the strategy and implementation are of
-	 * compatible types.
+	 * @param <T> Defines the strategy type and makes sure that the strategy and implementation
+	 *            are of compatible types.
 	 *
 	 * @return {@code this}, for method chaining
 	 *
@@ -138,11 +138,11 @@ public BootstrapServiceRegistryBuilder applyStrategySelectors(StrategyRegistrati
 	}
 
 	/**
-	 * By default, when a ServiceRegistry is no longer referenced by any other
-	 * registries as a parent it will be closed.
+	 * By default, when a {@link ServiceRegistry} is no longer referenced by
+	 * any other registries as a parent it will be closed.
 	 * <p>
-	 * Some applications that explicitly build "shared registries" may want to
-	 * circumvent that behavior.
+	 * Some applications that explicitly build "shared registries" may want
+	 * to circumvent that behavior.
 	 * <p>
 	 * This method indicates that the registry being built should not be
 	 * automatically closed.  The caller agrees to take responsibility to
@@ -156,8 +156,7 @@ public BootstrapServiceRegistryBuilder disableAutoClose() {
 	}
 
 	/**
-	 * See the discussion on {@link #disableAutoClose}.  This method enables
-	 * the auto-closing.
+	 * See the discussion on {@link #disableAutoClose}. This method enables the auto-closing.
 	 *
 	 * @return this, for method chaining
 	 */
@@ -202,7 +201,7 @@ public BootstrapServiceRegistry build() {
 	}
 
 	/**
-	 * Destroy a service registry.  Applications should only destroy registries they have explicitly created.
+	 * Destroy a service registry. Clients should only destroy registries they have created.
 	 *
 	 * @param serviceRegistry The registry to be closed.
 	 */

hibernate-core/src/main/java/org/hibernate/integrator/spi/Integrator.java

@@ -14,6 +14,9 @@
 
 /**
  * Contract for extensions that integrate with Hibernate.
+ * <p>
+ * An implementation of {@code Integrator} is discoverable via the standard Java
+ * {@link java.util.ServiceLoader} facility.
  *
  * @implNote {@link #integrate(Metadata, BootstrapContext, SessionFactoryImplementor)}
  *           is called during the process of {@linkplain SessionFactoryImplementor

hibernate-core/src/main/java/org/hibernate/integrator/spi/package-info.java

@@ -6,9 +6,9 @@
  */
 
 /**
- * An SPI for extensions which integrate with Hibernate via the {@link org.hibernate.service.Service} mechanism.
+ * An SPI for extensions which integrate with Hibernate via the Java {@link java.util.ServiceLoader} facility.
  * <p>
- * Examples {@linkplain org.hibernate.integrator.spi.Integrator integrators} include: Envers, Hibernate Search,
+ * Example {@linkplain org.hibernate.integrator.spi.Integrator integrators} include: Envers, Hibernate Search,
  * Hibernate Reactive, and {@linkplain org.hibernate.boot.beanvalidation.BeanValidationIntegrator Bean Validation}.
  *
  * @see org.hibernate.integrator.spi.Integrator

hibernate-core/src/main/java/org/hibernate/jpa/HibernatePersistenceProvider.java

@@ -112,7 +112,7 @@ private EntityManagerFactoryBuilder getEntityManagerFactoryBuilderOrNull(String
 				continue;
 			}
 
-			if (providedClassLoaderService != null) {
+			if ( providedClassLoaderService != null ) {
 				return getEntityManagerFactoryBuilder( persistenceUnit, integration, providedClassLoaderService );
 			}
 			else {

hibernate-core/src/main/java/org/hibernate/jpa/boot/spi/package-info.java

@@ -6,8 +6,10 @@
  */
 
 /**
- * An SPI controlling and integrating with the bootstrap process for the
- * Jakarta Persistence {@link jakarta.persistence.EntityManagerFactory}.
+ * An SPI used to {@linkplain org.hibernate.jpa.boot.spi.Bootstrap initiate}
+ * and {@linkplain org.hibernate.jpa.boot.spi.EntityManagerFactoryBuilder control}
+ * the JPA bootstrap process, along with SPI interfaces allowing certain sorts of
+ * extensions to be contributed during the bootstrap process.
  *
  * @author Steve Ebersole
  */

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

@@ -6,31 +6,49 @@
  */
 
 /**
- * Responsible for dealing with certain details of compliance with the
- * JPA specification.
+ * The packages in this namespace are responsible for implementing certain
+ * requirements of the JPA specification, especially things which are only
+ * needed when Hibernate is acting as a JPA <em>persistence provider</em>.
  * <p>
- * Contains an {@linkplain org.hibernate.jpa.HibernatePersistenceProvider
- * implementation} of a JPA {@link jakarta.persistence.spi.PersistenceProvider}.
+ * This package contains an
+ * {@linkplain org.hibernate.jpa.HibernatePersistenceProvider implementation}
+ * of a JPA {@link jakarta.persistence.spi.PersistenceProvider}. You may
+ * choose Hibernate as your JPA persistence provider by including the
+ * following line in {@code persistence.xml}:
+ * <pre>{@code <provider>org.hibernate.jpa.HibernatePersistenceProvider</provider>}</pre>
+ * When working with the Hibernate persistence provider, keep in mind that:
+ * <ul>
+ * <li>the {@link jakarta.persistence.EntityManagerFactory} is also a
+ *     {@link org.hibernate.SessionFactory},
+ * <li>every {@link jakarta.persistence.EntityManager} is also a
+ *     {@link org.hibernate.Session}, and
+ * <li>every {@link jakarta.persistence.Query} is also a
+ *     {@link org.hibernate.query.Query}.
+ * </ul>
  * <p>
- * Enumerates the {@linkplain jakarta.persistence.Query#setHint hints}
- * recognized by Hibernate:
+ * Thus, Hibernate's many powerful extensions to the JPA specification are
+ * always readily accessible.
  * <ul>
- * <li>{@link org.hibernate.jpa.SpecHints} enumerates the standard hints
- *     defined by the JPA specification.
- * <li>{@link org.hibernate.jpa.HibernateHints} enumerates hints defined
- *     by Hibernate.
+ * <li>The subpackage {@link org.hibernate.jpa.boot.spi} contains the SPI of
+ *     this persistence provider, including an SPI used to
+ *     {@linkplain org.hibernate.jpa.boot.spi.Bootstrap bootstrap} the JPA
+ *     provider, and interfaces which may be implemented to contribute extensions
+ *     during of the bootstrap process.
+ * <li>The package {@link org.hibernate.jpa.event} implements support for JPA
+ *     {@linkplain jakarta.persistence.EntityListeners event listeners}.
+ * <li>The package {@link org.hibernate.jpa.spi} provides SPIs for managing cases
+ *     where Hibernate intentionally violates the JPA specification by default
+ *     (something Hibernate only does when it has a really good reason to do so).
  * </ul>
  * <p>
- * Concerns handled by subpackages include:
+ * Finally, we have two interfaces which enumerate the JPA
+ * {@linkplain jakarta.persistence.Query#setHint query hints} recognized by
+ * Hibernate:
  * <ul>
- * <li>{@linkplain org.hibernate.jpa.boot.spi bootstrapping} JPA and
- *     integrating with the bootstrap process,
- * <li>calling JPA {@linkplain org.hibernate.jpa.event.spi event listeners},
- *     and
- * <li>managing cases where Hibernate intentionally
- *    {@linkplain org.hibernate.jpa.spi violates} the specification by
- *    default (something Hibernate only does if it has a really good
- *    reason to do so).
+ * <li>{@link org.hibernate.jpa.SpecHints} enumerates the standard hints
+ *     defined by the JPA specification, and
+ * <li>{@link org.hibernate.jpa.HibernateHints} enumerates hints defined
+ *     by Hibernate.
  * </ul>
  */
 package org.hibernate.jpa;

hibernate-core/src/main/java/org/hibernate/jpa/spi/JpaCompliance.java

@@ -22,8 +22,8 @@ public interface JpaCompliance {
 	 * translating a query as JPQL instead of HQL, as well as whether calls
 	 * to the {@link jakarta.persistence.Query} methods always throw the
 	 * exceptions defined by the specification.
-	 *
-	 * Deviations result in an exception if enabled
+	 * <p>
+	 * Deviations result in an exception, if enabled.
 	 *
 	 * @return {@code true} indicates to behave in the spec-defined way
 	 *

hibernate-core/src/main/java/org/hibernate/jpa/spi/package-info.java

@@ -6,7 +6,8 @@
  */
 
 /**
- * Manages cases where, by default, Hibernate intentionally violates the letter of the JPA specification.
+ * An SPI for managing cases where, by default, Hibernate intentionally violates
+ * the letter of the JPA specification.
  * <p>
  * (Hibernate only does this when there's an extremely strong justification.)
  *

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

@@ -6,10 +6,24 @@
  */
 package org.hibernate.service;
 
+import org.hibernate.service.spi.SessionFactoryServiceRegistry;
+
 import java.io.Serializable;
 
 /**
- * Marker interface for services.
+ * Marker interface for services. Services usually belong to a {@link ServiceRegistry}.
+ * <ul>
+ * <li>Services may be contributed to a {@link SessionFactoryServiceRegistry} using an
+ *     {@link org.hibernate.integrator.spi.Integrator}, which is automatically discoved
+ *     via the Java {@link java.util.ServiceLoader} facility.
+ * <li>Alternatively, a service may be directly contributed to a
+ *     {@link org.hibernate.service.spi.SessionFactoryServiceRegistryBuilder} either
+ *     by registering an actual instance of the {@code Service}, or by registering a
+ *     {@link org.hibernate.service.spi.ServiceInitiator}.
+ * <li>Other ways to contribute service implementations include
+ *     {@link org.hibernate.boot.registry.BootstrapServiceRegistryBuilder} and
+ *     {@link org.hibernate.boot.registry.StandardServiceRegistryBuilder}.
+ * </ul>
  * <p>
  * All services must be {@link Serializable}!
  *

hibernate-core/src/main/java/org/hibernate/service/internal/AbstractServiceRegistryImpl.java

@@ -36,7 +36,7 @@
 import org.hibernate.service.spi.Stoppable;
 
 /**
- * Basic implementation of the ServiceRegistry and ServiceRegistryImplementor contracts
+ * Basic implementation of the {@link ServiceRegistry} and {@link ServiceRegistryImplementor} contracts.
  *
  * @author Steve Ebersole
  * @author Sanne Grinovero

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

@@ -9,5 +9,18 @@
  * Defines a framework for pluggable {@linkplain org.hibernate.service.Service services},
  * allowing for customization of key components of Hibernate, and abstraction of these
  * components as SPI interfaces.
+ * <p>
+ * Services usually belong to a {@link org.hibernate.service.ServiceRegistry}, since
+ * that's where Hibernate goes to find them.
+ * <p>
+ * Libraries may even contribute {@linkplain org.hibernate.integrator.spi.Integrator
+ * discoverable} service implementations via the Java {@link java.util.ServiceLoader}
+ * facility.
+ *
+ * @see org.hibernate.service.Service
+ * @see org.hibernate.service.ServiceRegistry
+ * @see org.hibernate.service.spi.ServiceInitiator
+ * @see org.hibernate.integrator.spi.Integrator
+ * @see org.hibernate.service.spi.SessionFactoryServiceRegistryBuilder
  */
 package org.hibernate.service;