Explicit documentation notes on standard Java reflection

See gh-29531

spring-core/src/main/java/org/springframework/core/DefaultParameterNameDiscoverer.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2021 the original author or authors.
+ * Copyright 2002-2022 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.
@@ -18,9 +18,9 @@
 
 /**
  * Default implementation of the {@link ParameterNameDiscoverer} strategy interface,
- * using the Java 8 standard reflection mechanism (if available), and falling back
- * to the ASM-based {@link LocalVariableTableParameterNameDiscoverer} for checking
- * debug information in the class file.
+ * using the Java 8 standard reflection mechanism, and falling back to the ASM-based
+ * {@link LocalVariableTableParameterNameDiscoverer} for checking debug information
+ * in the class file (e.g. for classes compiled with earlier Java versions).
  *
  * <p>If a Kotlin reflection implementation is present,
  * {@link KotlinReflectionParameterNameDiscoverer} is added first in the list and

spring-core/src/main/java/org/springframework/core/KotlinReflectionParameterNameDiscoverer.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2022 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.
@@ -31,11 +31,13 @@
  * {@link ParameterNameDiscoverer} implementation which uses Kotlin's reflection facilities
  * for introspecting parameter names.
  *
- * Compared to {@link StandardReflectionParameterNameDiscoverer}, it allows in addition to
+ * <p>Compared to {@link StandardReflectionParameterNameDiscoverer}, it allows in addition to
  * determine interface parameter names without requiring Java 8 -parameters compiler flag.
  *
  * @author Sebastien Deleuze
  * @since 5.0
+ * @see StandardReflectionParameterNameDiscoverer
+ * @see DefaultParameterNameDiscoverer
  */
 public class KotlinReflectionParameterNameDiscoverer implements ParameterNameDiscoverer {
 

spring-core/src/main/java/org/springframework/core/LocalVariableTableParameterNameDiscoverer.java

@@ -47,12 +47,18 @@
  * caches the ASM discovered information for each introspected Class, in a thread-safe
  * manner. It is recommended to reuse ParameterNameDiscoverer instances as far as possible.
  *
+ * <p>This discoverer variant is effectively superseded by the Java 8 based
+ * {@link StandardReflectionParameterNameDiscoverer} but included as a fallback still
+ * (for code not compiled with the standard "-parameters" compiler flag).
+ *
  * @author Adrian Colyer
  * @author Costin Leau
  * @author Juergen Hoeller
  * @author Chris Beams
  * @author Sam Brannen
  * @since 2.0
+ * @see StandardReflectionParameterNameDiscoverer
+ * @see DefaultParameterNameDiscoverer
  */
 public class LocalVariableTableParameterNameDiscoverer implements ParameterNameDiscoverer {
 

spring-core/src/main/java/org/springframework/core/StandardReflectionParameterNameDiscoverer.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2022 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.
@@ -26,10 +26,15 @@
  * {@link ParameterNameDiscoverer} implementation which uses JDK 8's reflection facilities
  * for introspecting parameter names (based on the "-parameters" compiler flag).
  *
+ * <p>This is a key element of {@link DefaultParameterNameDiscoverer} where it is being
+ * combined with {@link KotlinReflectionParameterNameDiscoverer} if Kotlin is present.
+ *
  * @author Juergen Hoeller
  * @since 4.0
  * @see java.lang.reflect.Method#getParameters()
  * @see java.lang.reflect.Parameter#getName()
+ * @see KotlinReflectionParameterNameDiscoverer
+ * @see DefaultParameterNameDiscoverer
  */
 public class StandardReflectionParameterNameDiscoverer implements ParameterNameDiscoverer {