add a code example lifted from the Native Bootstrapping guide to jdoc

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

@@ -6,20 +6,71 @@
  */
 
 /**
- * This package contains the contracts that make up the bootstrap API
+ * This package contains the interfaces that make up the bootstrap API
- * for Hibernate. That is, they collectively provide a way to specify
+ * for Hibernate. They collectively provide a way to specify configuration
- * configuration information and construct a new instance of
+ * information and construct a new instance of {@link org.hibernate.SessionFactory}.
- * {@link org.hibernate.SessionFactory}.
+ * <p>
+ * Configuring Hibernate using these APIs usually involves working with:
+ * <ol>
+ * <li>{@link org.hibernate.boot.registry.StandardServiceRegistryBuilder},
+ *     then
+ * <li>{@link org.hibernate.boot.MetadataSources} and
+ *     {@link org.hibernate.boot.MetadataBuilder}, and
+ * <li>finally, with {@link org.hibernate.boot.SessionFactoryBuilder}.
+ * </ol>
+ * <pre>
+ * StandardServiceRegistry standardRegistry =
+ *         new StandardServiceRegistryBuilder()
+ *                 // supply a configuration
+ *                 .configure("org/hibernate/example/hibernate.cfg.xml")
+ *                 // set a configuration property
+ *                 .applySetting(AvailableSettings.HBM2DDL_AUTO,
+ *                               SchemaAutoTooling.CREATE_DROP.externalForm())
+ *                 .build();
+ * MetadataBuilder metadataBuilder =
+ *         new MetadataSources(standardRegistry)
+ *                 // supply annotated classes
+ *                 .addAnnotatedClass(MyEntity.class)
+ *                 .addAnnotatedClassName("org.hibernate.example.Customer")
+ *                 // supply XML-based mappings
+ *                 .addResource("org/hibernate/example/Order.hbm.xml")
+ *                 .addResource("org/hibernate/example/Product.orm.xml")
+ *                 .getMetadataBuilder();
+ * Metadata metadata =
+ *         metadataBuilder
+ *                 // set the naming strategies
+ *                 .applyImplicitNamingStrategy(ImplicitNamingStrategyJpaCompliantImpl.INSTANCE)
+ *                 .applyPhysicalNamingStrategy(new CustomPhysicalNamingStrategy())
+ *                 // add a TypeContributor
+ *                 .applyTypes(new CustomTypeContributor())
+ *                 .build();
+ * SessionFactoryBuilder sessionFactoryBuilder =
+ *         metadata.getSessionFactoryBuilder();
+ * SessionFactory sessionFactory =
+ *         sessionFactoryBuilder
+ *                 // supply a factory-level Interceptor
+ *                 .applyInterceptor(new CustomSessionFactoryInterceptor());
+ *                 // add a custom observer
+ *                 .addSessionFactoryObservers(new CustomSessionFactoryObserver());
+ *                 // apply a CDI BeanManager (for JPA event listeners)
+ *                 .applyBeanManager(getBeanManager());
+ *                 .build();
+ * </pre>
+ * <p>
+ * In more advanced scenarios,
+ * {@link org.hibernate.boot.registry.BootstrapServiceRegistryBuilder}
+ * might also be used.
  * <p>
- * Configuring Hibernate using these APIs usually starts with
- * {@link org.hibernate.boot.MetadataBuilder} and
- * {@link org.hibernate.boot.registry.StandardServiceRegistryBuilder}.
  * See the <em>Native Bootstrapping</em> guide for more details.
  * <p>
  * Included in subpackages under this namespace are:
  * <ul>
+ * <li>{@linkplain org.hibernate.boot.registry implementations} of
+ *     {@link org.hibernate.service.ServiceRegistry} used during
+ *     the bootstrap process,
  * <li>implementations of {@link org.hibernate.boot.MetadataBuilder}
- *     and {@link org.hibernate.boot.Metadata},
+ *     and {@link org.hibernate.boot.Metadata}, and
+ *     {@link org.hibernate.boot.SessionFactoryBuilder},
  * <li>{@linkplain org.hibernate.boot.model.naming support} for
  *     {@link org.hibernate.boot.model.naming.ImplicitNamingStrategy}
  *     and {@link org.hibernate.boot.model.naming.PhysicalNamingStrategy},
@@ -27,16 +78,16 @@
  *     integration with the process of building metadata,
  * <li>internal code for parsing and interpreting mapping information
  *     declared in XML or using annotations,
- * <li>{@linkplain org.hibernate.boot.registry implementations} of
- *     {@link org.hibernate.service.ServiceRegistry} used during
- *     the bootstrap process,
  * <li>{@linkplain org.hibernate.boot.beanvalidation support} for
  *     integrating an implementation of Bean Validation, such as
- *     Hibernate Validator, and
+ *     <a href="https://hibernate.org/validator/">Hibernate Validator</a>,
+ *     and
  * <li>{@linkplain org.hibernate.boot.model.relational some SPIs}
- *     used for schema management including support for exporting
+ *     used for schema management, including support for exporting
  *     {@linkplain org.hibernate.boot.model.relational.AuxiliaryDatabaseObject
- *     auxiliary database objects}.
+ *     auxiliary database objects}, and for determining the
+ *     {@linkplain org.hibernate.boot.model.relational.ColumnOrderingStrategy
+ *     order of columns} in generated DDL statements.
  * </ul>
  */
 package org.hibernate.boot;

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

@@ -6,16 +6,19 @@
  */
 
 /**
- * Defines service registry contracts application are may utilize for configuring Hibernate.
+ * Defines {@linkplain org.hibernate.service.ServiceRegistry service registry} contracts a program may use for
+ * configuring Hibernate.
  * <p>
  * Service registries are hierarchical. That is, a child registry may "hide" or "override" services from its parent
  * registries. This allows for granular construction of registries as services become available.
  * <ol>
  * <li>
+ * <p>
  * {@link org.hibernate.boot.registry.BootstrapServiceRegistry} is the base service registry, and may be constructed via
  * {@link org.hibernate.boot.registry.BootstrapServiceRegistryBuilder} if customization is needed. For non-customized
  * usage, these APIs may be bypassed completely.
  * <li>
+ * <p>
  * The next level in a standard registry setup is the {@link org.hibernate.boot.registry.StandardServiceRegistry},
  * which may be constructed using {@link org.hibernate.boot.registry.StandardServiceRegistryBuilder} if customization
  * is needed. The builder optionally accepts s {@link org.hibernate.boot.registry.BootstrapServiceRegistry} to use as a

hibernate-core/src/main/java/org/hibernate/event/service/spi/EventListenerRegistry.java

@@ -6,7 +6,6 @@
  */
 package org.hibernate.event.service.spi;
 
-import org.hibernate.boot.spi.MetadataImplementor;
 import org.hibernate.event.spi.EventType;
 import org.hibernate.service.Service;