diff --git a/junit5/src/main/java/org/jboss/weld/junit5/WeldInitiator.java b/junit5/src/main/java/org/jboss/weld/junit5/WeldInitiator.java
index fe8f9a6c..682421fe 100644
--- a/junit5/src/main/java/org/jboss/weld/junit5/WeldInitiator.java
+++ b/junit5/src/main/java/org/jboss/weld/junit5/WeldInitiator.java
@@ -70,8 +70,13 @@ public static WeldInitiator of(Class<?>... beanClasses) {
 
     /**
      * The container is configured through a provided {@link Weld} instance.
+     * <p>
+     * Provided instance of {@link Weld} should be kept in the same scope as the resulting {@link WeldInitiator}.
+     * I.e. if {@link Weld} instance is kept in a static field, so should be the resulting {@link WeldInitiator}.
+     * Failing to uphold this can lead to repetitive configuration of the same {@link Weld} instance which in turn results in
+     * unexpected container setup/behavior.
      *
-     * @param weld
+     * @param weld instance of {@link Weld} used to create {@link WeldInitiator}
      * @return a new WeldInitiator instance
      */
     public static WeldInitiator of(Weld weld) {
@@ -120,8 +125,13 @@ public static Builder from(Class<?>... beanClasses) {
 
     /**
      * Create a builder instance.
+     * <p>
+     * Provided instance of {@link Weld} should be kept in the same scope as the resulting {@link WeldInitiator}.
+     * I.e. if {@link Weld} instance is kept in a static field, so should be the resulting {@link WeldInitiator}.
+     * Failing to uphold this can lead to repetitive configuration of the same {@link Weld} instance which in turn results in
+     * unexpected container setup/behavior.
      *
-     * @param weld
+     * @param weld instance of {@link Weld} used as a basis for this {@link WeldInitiator.Builder}
      * @return a builder instance
      * @see #of(Weld)
      */