Polish documentation for RegisterReflection

See gh-29194

framework-docs/modules/ROOT/pages/core/aot.adoc

@@ -517,32 +517,28 @@ Library authors can reuse this annotation for their own purposes.
 If components other than Spring beans need to be processed, a `BeanFactoryInitializationAotProcessor` can detect the relevant types and use `ReflectiveRuntimeHintsRegistrar` to process them.
 
 
-[[aot.hints.register-reflection-for-binding]]
-=== `@RegisterReflectionForBinding`
+[[aot.hints.register-reflection]]
+=== `@RegisterReflection`
 
-{spring-framework-api}/aot/hint/annotation/RegisterReflectionForBinding.html[`@RegisterReflectionForBinding`] is a specialization of `@Reflective` that registers the need for serializing arbitrary types.
-A typical use case is the use of DTOs that the container cannot infer, such as using a web client within a method body.
+{spring-framework-api}/aot/hint/annotation/RegisterReflection.html[`@RegisterReflection`] is a specialization of `@Reflective` that provides a declarative way of registering reflection for arbitrary types.
 
-`@RegisterReflectionForBinding` can be applied to any Spring bean at the class level, but it can also be applied directly to a method, field, or constructor to better indicate where the hints are actually required.
-The following example registers `Account` for serialization.
+In the following example, public constructors and public methods can be invoked via reflection on `AccountService`:
 
-[tabs]
-======
-Java::
-+
-[source,java,indent=0,subs="verbatim,quotes",role="primary"]
-----
-	@Component
-	public class OrderService {
+include-code::./MyConfiguration[tag=snippet,indent=0]
 
-		@RegisterReflectionForBinding(Account.class)
-		public void process(Order order) {
-			// ...
-		}
+`@RegisterReflection` can be applied to any Spring bean at the class level, but it can also be applied directly to a method to better indicate where the hints are actually required.
 
-	}
-----
-======
+`@RegisterReflection` can be used as a meta-annotation to provide more specific needs.
+{spring-framework-api}/aot/hint/annotation/RegisterReflectionForBinding.html[`@RegisterReflectionForBinding`] is such composed annotation and registers the need for serializing arbitrary types.
+A typical use case is the use of DTOs that the container cannot infer, such as using a web client within a method body.
+
+The following example registers `Order` for serialization.
+
+include-code::./OrderService[tag=snippet,indent=0]
+
+This registers hints for constructors, fields, properties, and record components of `Order`.
+Hints are also registered for types transitively used on properties and record components.
+In other words, if `Order` exposes others types, hints are registered for those as well.
 
 [[aot.hints.testing]]
 === Testing Runtime Hints

framework-docs/src/main/java/org/springframework/docs/core/aot/hints/registerreflection/MyConfiguration.java

@@ -0,0 +1,31 @@
+/*
+ * 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.docs.core.aot.hints.registerreflection;
+
+import org.springframework.aot.hint.MemberCategory;
+import org.springframework.aot.hint.annotation.RegisterReflection;
+import org.springframework.context.annotation.Configuration;
+
+// tag::snippet[]
+@Configuration
+@RegisterReflection(classes = AccountService.class, memberCategories =
+		{ MemberCategory.INVOKE_PUBLIC_CONSTRUCTORS, MemberCategory.INVOKE_PUBLIC_METHODS })
+class MyConfiguration {
+}
+// end::snippet[]
+
+class AccountService {}

framework-docs/src/main/java/org/springframework/docs/core/aot/hints/registerreflection/OrderService.java

@@ -0,0 +1,34 @@
+/*
+ * 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.docs.core.aot.hints.registerreflection;
+
+import org.springframework.aot.hint.annotation.RegisterReflectionForBinding;
+import org.springframework.stereotype.Component;
+
+// tag::snippet[]
+@Component
+class OrderService {
+
+	@RegisterReflectionForBinding(Order.class)
+	public void process(Order order) {
+		// ...
+	}
+
+}
+// end::snippet[]
+
+record Order() {}

spring-context/src/main/java/org/springframework/context/annotation/ImportRuntimeHints.java

@@ -63,7 +63,7 @@
  * @since 6.0
  * @see org.springframework.aot.hint.RuntimeHints
  * @see org.springframework.aot.hint.annotation.Reflective
- * @see org.springframework.aot.hint.annotation.RegisterReflectionForBinding
+ * @see org.springframework.aot.hint.annotation.RegisterReflection
  */
 @Target({ElementType.TYPE, ElementType.METHOD})
 @Retention(RetentionPolicy.RUNTIME)

spring-test/src/main/java/org/springframework/test/context/aot/TestRuntimeHintsRegistrar.java

@@ -37,7 +37,7 @@
  * <p>As an alternative to implementing and registering a {@code TestRuntimeHintsRegistrar},
  * you may choose to annotate a test class with
  * {@link org.springframework.aot.hint.annotation.Reflective @Reflective},
- * {@link org.springframework.aot.hint.annotation.RegisterReflectionForBinding @RegisterReflectionForBinding},
+ * {@link org.springframework.aot.hint.annotation.RegisterReflection @RegisterReflection},
  * or {@link org.springframework.context.annotation.ImportRuntimeHints @ImportRuntimeHints}.
  *
  * @author Sam Brannen