Document that TestContextAnnotationUtils is required for @⁠Nested sup…

…port

Closes gh-33586

framework-docs/modules/ROOT/pages/testing/testcontext-framework/support-classes.adoc

@@ -542,6 +542,14 @@ any of its subclasses and nested classes. Thus, you may annotate a top-level tes
 with `@NestedTestConfiguration`, and that will apply to all of its nested test classes
 recursively.
 
+[TIP]
+====
+If you are developing a component that integrates with the Spring TestContext Framework
+and needs to support annotation inheritance within enclosing class hierarchies, you must
+use the annotation search utilities provided in `TestContextAnnotationUtils` in order to
+honor `@NestedTestConfiguration` semantics.
+====
+
 In order to allow development teams to change the default to `OVERRIDE` – for example,
 for compatibility with Spring Framework 5.0 through 5.2 – the default mode can be changed
 globally via a JVM system property or a `spring.properties` file in the root of the

spring-test/src/main/java/org/springframework/test/context/NestedTestConfiguration.java

@@ -58,10 +58,16 @@
  * <p>This annotation may be used as a <em>meta-annotation</em> to create custom
  * <em>composed annotations</em>.
  *
- * <p>As of Spring Framework 5.3, the use of this annotation typically only makes
- * sense in conjunction with {@link org.junit.jupiter.api.Nested @Nested} test
- * classes in JUnit Jupiter; however, there may be other testing frameworks with
- * support for nested test classes that could also make use of this annotation.
+ * <p>The use of this annotation typically only makes sense in conjunction with
+ * {@link org.junit.jupiter.api.Nested @Nested} test classes in JUnit Jupiter;
+ * however, there may be other testing frameworks with support for nested test
+ * classes that could also make use of this annotation.
+ *
+ * <p>If you are developing a component that integrates with the Spring TestContext
+ * Framework and needs to support annotation inheritance within enclosing class
+ * hierarchies, you must use the annotation search utilities provided in
+ * {@link TestContextAnnotationUtils} in order to honor
+ * {@code @NestedTestConfiguration} semantics.
  *
  * <h3>Supported Annotations</h3>
  * <p>The <em>Spring TestContext Framework</em> honors {@code @NestedTestConfiguration}
@@ -89,6 +95,7 @@
  * @since 5.3
  * @see EnclosingConfiguration#INHERIT
  * @see EnclosingConfiguration#OVERRIDE
+ * @see TestContextAnnotationUtils
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)

spring-test/src/main/java/org/springframework/test/context/TestContextAnnotationUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2023 the original author or authors.
+ * Copyright 2002-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -47,7 +47,8 @@
  * and {@link AnnotatedElementUtils}, while transparently honoring
  * {@link NestedTestConfiguration @NestedTestConfiguration} semantics.
  *
- * <p>Mainly for internal use within the <em>Spring TestContext Framework</em>.
+ * <p>Mainly for internal use within the <em>Spring TestContext Framework</em>
+ * but also supported for third-party integrations with the TestContext framework.
  *
  * <p>Whereas {@code AnnotationUtils} and {@code AnnotatedElementUtils} provide
  * utilities for <em>getting</em> or <em>finding</em> annotations,
@@ -70,6 +71,7 @@
  * @see AnnotationUtils
  * @see AnnotatedElementUtils
  * @see AnnotationDescriptor
+ * @see NestedTestConfiguration
  */
 public abstract class TestContextAnnotationUtils {