improve Javadoc for VertxInstance stuff

hibernate-reactive-core/src/main/java/org/hibernate/reactive/vertx/VertxInstance.java

@@ -7,19 +7,27 @@
 
 import io.vertx.core.Vertx;
 
-import org.hibernate.reactive.pool.impl.DefaultSqlClientPool;
 import org.hibernate.service.Service;
 
 /**
- * Used by {@link DefaultSqlClientPool} and
- * {@link org.hibernate.reactive.context.impl.VertxContext}
- * to obtain an instance of {@link Vertx}. The default instance is
- * {@link org.hibernate.reactive.vertx.impl.DefaultVertxInstance}.
+ * Used by {@link org.hibernate.reactive.pool.impl.DefaultSqlClientPool}
+ * and {@link org.hibernate.reactive.context.impl.VertxContext} to
+ * obtain an instance of {@link Vertx}.
  * <p>
- * A program may integrate a custom {@link VertxInstance}
- * with Hibernate Reactive by contributing a new service using a
- * {@link org.hibernate.boot.registry.StandardServiceInitiator}
- * or from code-based Hibernate configuration by calling
+ * The default implementation is
+ * {@link org.hibernate.reactive.vertx.impl.DefaultVertxInstance},
+ * which creates a new instance of {@code Vertx} if there is no
+ * instance already associated with the calling thread. This default
+ * behavior may cause problems in programs which have an instance of
+ * {@code Vertx} whose lifecycle is managed externally to Hibernate
+ * Reactive, and in such cases
+ * {@link org.hibernate.reactive.vertx.impl.ProvidedVertxInstance}
+ * or a custom-written {@code VertxInstance} should be used.
+ * <p>
+ * A program may integrate a custom {@link VertxInstance} with
+ * Hibernate Reactive by contributing a new service using a
+ * {@link org.hibernate.boot.registry.StandardServiceInitiator} or
+ * from code-based Hibernate configuration by calling the method
  * {@link org.hibernate.reactive.provider.ReactiveServiceRegistryBuilder#addService}.
  *
  * <pre>{@code

hibernate-reactive-core/src/main/java/org/hibernate/reactive/vertx/impl/DefaultVertxInstance.java

@@ -20,9 +20,15 @@
  * A singleton instance of {@link Vertx} that is created on
  * demand and destroyed automatically along with the Hibernate
  * {@link org.hibernate.SessionFactory#close() session factory}.
+ * <p>
+ * Programs which require Hibernate reactive to use an instance
+ * of {@code Vertx} whose lifecycle is managed externally to
+ * Hibernate Reactive should use {@link ProvidedVertxInstance}
+ * instead.
  *
  * @author Sanne Grinovero <[email protected]>
- * @see ProvidedVertxInstance if you need to a different instance
+ *
+ * @see ProvidedVertxInstance
  */
 public final class DefaultVertxInstance implements VertxInstance, Stoppable, Startable {
 

hibernate-reactive-core/src/main/java/org/hibernate/reactive/vertx/impl/ProvidedVertxInstance.java

@@ -13,7 +13,7 @@
 
 /**
  * An implementation of {@link VertxInstance} which allows the client
- * to provide an instance of {@link Vertx} whose lifecyle is managed
+ * to provide an instance of {@link Vertx} whose lifecycle is managed
  * externally to Hibernate Reactive. The {@code ProvidedVertxInstance}
  * must be registered explicitly with Hibernate by calling
  * {@link org.hibernate.reactive.provider.ReactiveServiceRegistryBuilder#addService}.

hibernate-reactive-core/src/main/java/org/hibernate/reactive/vertx/package-info.java

@@ -1,5 +1,7 @@
 /**
- * Integration with Vert.x.
+ * Integration with Vert.x. Allows a program to customize how
+ * instances of {@link io.vertx.core.Vertx} should be obtained
+ * by Hibernate Reactive.
  *
  * @see org.hibernate.reactive.vertx.VertxInstance
  */