From 7c79b90ffd67281241def0747c100e2b7374232d Mon Sep 17 00:00:00 2001
From: Matej Novotny <manovotn@redhat.com>
Date: Tue, 30 Jan 2024 14:08:37 +0100
Subject: [PATCH] Clarify that WeldInitiator.from() and WeldInitiator.of()
 should use the same variable scope

---
 .../java/org/jboss/weld/junit5/WeldInitiator.java  | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

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)
      */