From 8d03ec38308d98e901232d3e24b8f80e8745e937 Mon Sep 17 00:00:00 2001
From: khj68 <junthewise@gmail.com>
Date: Sun, 17 Aug 2025 17:26:48 +0900
Subject: [PATCH] Improve Javadoc of ApplicationEvents to clarify preferred
 usage

This commit reorders and clarifies the usage instructions for
ApplicationEvents to:

1. Recommend method parameter injection as the primary approach, since
   ApplicationEvents has a per-method lifecycle
2. Clarify that ApplicationEvents is not a general Spring bean and
   cannot be constructor-injected
3. Explicitly state that field injection is an alternative approach

This addresses confusion where developers expect ApplicationEvents to
behave like a regular Spring bean eligible for constructor injection.

Closes gh-35297

Signed-off-by: khj68 <junthewise@gmail.com>
---
 .../test/context/event/ApplicationEvents.java        | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/spring-test/src/main/java/org/springframework/test/context/event/ApplicationEvents.java b/spring-test/src/main/java/org/springframework/test/context/event/ApplicationEvents.java
index 3653d4da957e..5bdc8b3c7973 100644
--- a/spring-test/src/main/java/org/springframework/test/context/event/ApplicationEvents.java
+++ b/spring-test/src/main/java/org/springframework/test/context/event/ApplicationEvents.java
@@ -33,12 +33,14 @@
  * to be manually registered if you have custom configuration via
  * {@link org.springframework.test.context.TestExecutionListeners @TestExecutionListeners}
  * that does not include the default listeners.</li>
- * <li>Annotate a field of type {@code ApplicationEvents} with
+ * <li>With JUnit Jupiter, declare a parameter of type {@code ApplicationEvents}
+ * in a test or lifecycle method. Since {@code ApplicationEvents} is scoped to the
+ * lifecycle of the current test method, this is the recommended approach.</li>
+ * <li>Alternatively, you can annotate a field of type {@code ApplicationEvents} with
  * {@link org.springframework.beans.factory.annotation.Autowired @Autowired} and
- * use that instance of {@code ApplicationEvents} in your test and lifecycle methods.</li>
- * <li>With JUnit Jupiter, you may optionally declare a parameter of type
- * {@code ApplicationEvents} in a test or lifecycle method as an alternative to
- * an {@code @Autowired} field in the test class.</li>
+ * use that instance of {@code ApplicationEvents} in your test and lifecycle methods.
+ * Note that {@code ApplicationEvents} is not a general Spring bean and is specifically
+ * designed for use within test methods.</li>
  * </ul>
  *
  * @author Sam Brannen