Additional documentation notes on Java/Kotlin parameter name retention

See gh-29563

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.
@@ -30,11 +30,13 @@ import org.springframework.lang.Nullable;
  * {@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,21 @@ import org.springframework.util.ClassUtils;
  * 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 class is deprecated in the 6.0 generation and scheduled for removal in 6.1
+ * since it is effectively superseded by {@link StandardReflectionParameterNameDiscoverer}.
+ * For the time being, this discoverer logs a warning every time it actually inspects a
+ * class file which is particularly useful for identifying remaining gaps in usage of
+ * the standard "-parameters" compiler flag, and also unintended over-inspection of
+ * e.g. JDK core library classes (which are not compiled with the "-parameters" flag).
+ *
  * @author Adrian Colyer
  * @author Costin Leau
  * @author Juergen Hoeller
  * @author Chris Beams
  * @author Sam Brannen
  * @since 2.0
+ * @see StandardReflectionParameterNameDiscoverer
+ * @see DefaultParameterNameDiscoverer
  * @deprecated as of 6.0.1, in favor of {@link StandardReflectionParameterNameDiscoverer}
  * (with the "-parameters" compiler flag)
  */

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 @@ import org.springframework.lang.Nullable;
  * {@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 {