Improve how the build deals with javadoc invalid references

This commit improves how the build deals with javadoc invalid references
in two ways.

Link/see references that are temporarily invalid during javadoc
generation of individual modules are better masked by using the option
`Xdoclint:syntax` instead of `Xdoclint:none` (warnings were still
visible in some cases, e.g. when individually building the javadoc for
a specific module).

Global javadoc-building task `api` now combines `syntax` and `reference`
`Xdoclint` groups, allowing to raise truly invalid references even when
all the modules have been aggregated.

This commit also fixes the 20+ errors which appeared following the later
change in doclet configuration.

Closes gh-30428

Author: simonbasle

framework-docs/framework-docs.gradle

@@ -104,7 +104,7 @@ task api(type: Javadoc) {
 		overview = "framework-docs/src/docs/api/overview.html"
 		splitIndex = true
 		links(project.ext.javadocLinks)
-		addBooleanOption('Xdoclint:syntax', true) // only check syntax with doclint
+		addBooleanOption('Xdoclint:syntax,reference', true) // only check syntax and reference with doclint
 		addBooleanOption('Werror', true) // fail build on Javadoc warnings
 	}
 	source moduleProjects.collect { project ->

framework-docs/modules/ROOT/pages/appendix.adoc

@@ -25,7 +25,7 @@ The following table lists all currently supported Spring properties.
 | `spring.beaninfo.ignore`
 | Instructs Spring to use the `Introspector.IGNORE_ALL_BEANINFO` mode when calling the
 JavaBeans `Introspector`. See
-{api-spring-framework}++/beans/CachedIntrospectionResults.html#IGNORE_BEANINFO_PROPERTY_NAME++[`CachedIntrospectionResults`]
+{api-spring-framework}++/beans/StandardBeanInfoFactory.html#IGNORE_BEANINFO_PROPERTY_NAME++[`CachedIntrospectionResults`]
 for details.
 
 | `spring.expression.compiler.mode`

gradle/spring-module.gradle

@@ -72,10 +72,13 @@ javadoc {
 	options.header = project.name
 	options.use = true
 	options.links(project.ext.javadocLinks)
-	options.addStringOption("Xdoclint:none", "-quiet")
+	// Check for syntax during linting. 'none' doesn't seem to work in suppressing
+	// all linting warnings all the time (see/link references most notably).
+	options.addStringOption("Xdoclint:syntax", "-quiet")
 
 	// Suppress warnings due to cross-module @see and @link references.
-	// Note that global 'api' task does display all warnings.
+	// Note that global 'api' task does display all warnings, and
+	// checks for 'reference' on top of 'syntax'.
 	logging.captureStandardError LogLevel.INFO
 	logging.captureStandardOutput LogLevel.INFO  // suppress "## warnings" message
 }

spring-core/src/main/java/org/springframework/cglib/core/CodeEmitter.java

@@ -737,7 +737,6 @@ public void box(Type type) {
      * on the top of the stack with the unwrapped (primitive)
      * equivalent. For example, Character -> char.
      * @param type the class indicating the desired type of the top stack value
-     * @return true if the value was unboxed
      */
     public void unbox(Type type) {
         Type t = Constants.TYPE_NUMBER;

spring-core/src/main/java/org/springframework/cglib/proxy/InterfaceMaker.java

@@ -74,7 +74,7 @@ public void add(Method method) {
      * Add all the public methods in the specified class.
      * Methods from superclasses are included, except for methods declared in the base
      * Object class (e.g. <code>getClass</code>, <code>equals</code>, <code>hashCode</code>).
-     * @param class the class containing the methods to add to the interface
+     * @param clazz the class containing the methods to add to the interface
      */
     public void add(Class clazz) {
         Method[] methods = clazz.getMethods();

spring-core/src/main/java/org/springframework/cglib/proxy/InvocationHandler.java

@@ -28,7 +28,7 @@ public interface InvocationHandler
 extends Callback
 {
     /**
-     * @see java.lang.reflect.InvocationHandler#invoke(java.lang.Object, java.lang.reflect.Method, java.lang.Object)
+     * @see java.lang.reflect.InvocationHandler#invoke(java.lang.Object, java.lang.reflect.Method, java.lang.Object[])
      */
     public Object invoke(Object proxy, Method method, Object[] args) throws Throwable;
 

spring-core/src/main/java/org/springframework/cglib/transform/impl/UndeclaredThrowableStrategy.java

@@ -25,7 +25,7 @@
 import org.springframework.cglib.transform.TransformingClassGenerator;
 
 /**
- * A {@link GeneratorStrategy} suitable for use with {@link org.springframework.cglib.Enhancer} which
+ * A {@link GeneratorStrategy} suitable for use with {@link org.springframework.cglib.proxy.Enhancer} which
  * causes all undeclared exceptions thrown from within a proxied method to be wrapped
  * in an alternative exception of your choice.
  */

spring-core/src/main/java/org/springframework/cglib/util/ParallelSorter.java

@@ -64,7 +64,6 @@ protected ParallelSorter() {
      * @param arrays An array of arrays to sort. The arrays may be a mix
      * of primitive and non-primitive types, but should all be the same
      * length.
-     * @param loader ClassLoader for generated class, uses "current" if null
      */
     public static ParallelSorter create(Object[] arrays) {
         Generator gen = new Generator();
@@ -135,8 +134,7 @@ public void mergeSort(int index, int lo, int hi) {
     /**
      * Sort the arrays using an in-place merge sort.
      * @param index array (column) to sort by
-     * @param lo starting array index (row), inclusive
-     * @param hi ending array index (row), exclusive
+     * @param cmp Comparator to use if the specified column is non-primitive
      */
     public void mergeSort(int index, Comparator cmp) {
         mergeSort(index, 0, len(), cmp);

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

@@ -38,7 +38,7 @@
  *
  * @author Juergen Hoeller
  * @since 3.2.7
- * @see org.springframework.beans.CachedIntrospectionResults#IGNORE_BEANINFO_PROPERTY_NAME
+ * @see org.springframework.beans.StandardBeanInfoFactory#IGNORE_BEANINFO_PROPERTY_NAME
  * @see org.springframework.context.index.CandidateComponentsIndexLoader#IGNORE_INDEX
  * @see org.springframework.core.env.AbstractEnvironment#IGNORE_GETENV_PROPERTY_NAME
  * @see org.springframework.expression.spel.SpelParserConfiguration#SPRING_EXPRESSION_COMPILER_MODE_PROPERTY_NAME

spring-jdbc/src/main/java/org/springframework/jdbc/datasource/DriverManagerDataSource.java

@@ -48,9 +48,9 @@
  * the container. Such a DataSource can be exposed as a DataSource bean in a Spring
  * ApplicationContext via {@link org.springframework.jndi.JndiObjectFactoryBean},
  * for seamless switching to and from a local DataSource bean like this class.
- * For tests, you can then either set up a mock JNDI environment through Spring's
- * {@link org.springframework.mock.jndi.SimpleNamingContextBuilder}, or switch the
- * bean definition to a local DataSource (which is simpler and thus recommended).
+ * For tests, you can then either set up a mock JNDI environment through complete
+ * solutions from third parties such as <a href="https://github.com/h-thurow/Simple-JNDI">Simple-JNDI</a>,
+ * or switch the bean definition to a local DataSource (which is simpler and thus recommended).
  *
  * <p>This {@code DriverManagerDataSource} class was originally designed alongside
  * <a href="https://commons.apache.org/proper/commons-dbcp">Apache Commons DBCP</a>

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

@@ -81,7 +81,6 @@ default boolean isContextLoaded(MergedContextConfiguration mergedContextConfigur
 	 * the application context
 	 * @see #isContextLoaded
 	 * @see #closeContext
-	 * @see #setContextFailureProcessor
 	 */
 	ApplicationContext loadContext(MergedContextConfiguration mergedContextConfiguration);
 

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

@@ -66,7 +66,7 @@
  * example, {@link ContextConfiguration#inheritLocations}.
  *
  * @author Sam Brannen
- * @since 5.3, though originally since 4.0 as {@link org.springframework.test.util.MetaAnnotationUtils}
+ * @since 5.3, though originally since 4.0 as {@code org.springframework.test.util.MetaAnnotationUtils}
  * @see AnnotationUtils
  * @see AnnotatedElementUtils
  * @see AnnotationDescriptor

spring-test/src/main/java/org/springframework/test/context/support/AbstractTestContextBootstrapper.java

@@ -494,13 +494,13 @@ else if (logger.isDebugEnabled()) {
 	 * interaction with the {@code ContextCache}.
 	 * <p>The default implementation delegates to
 	 * {@code getBootstrapContext().getCacheAwareContextLoaderDelegate()} and
-	 * supplies the returned delegate the configured
-	 * {@link #getApplicationContextFailureProcessor() ApplicationContextFailureProcessor}.
+	 * the default one will load {@link org.springframework.test.context.ApplicationContextFailureProcessor}
+	 * via the service loading mechanism.
 	 * <p>Concrete subclasses may choose to override this method to return a custom
 	 * {@code CacheAwareContextLoaderDelegate} implementation with custom
 	 * {@link org.springframework.test.context.cache.ContextCache ContextCache} support.
 	 * @return the context loader delegate (never {@code null})
-	 * @see #getApplicationContextFailureProcessor()
+	 * @see org.springframework.test.context.ApplicationContextFailureProcessor
 	 */
 	protected CacheAwareContextLoaderDelegate getCacheAwareContextLoaderDelegate() {
 		return getBootstrapContext().getCacheAwareContextLoaderDelegate();

spring-test/src/main/java/org/springframework/test/util/TestSocketUtils.java

@@ -28,7 +28,7 @@
  * Simple utility for finding available TCP ports on {@code localhost} for use in
  * integration testing scenarios.
  *
- * <p>This is a limited form of {@link org.springframework.util.SocketUtils} which
+ * <p>This is a limited form of {@code org.springframework.util.SocketUtils}, which
  * has been deprecated since Spring Framework 5.3.16 and removed in Spring
  * Framework 6.0.
  *

spring-test/src/main/java/org/springframework/test/web/client/AbstractRequestExpectationManager.java

@@ -110,7 +110,7 @@ protected void afterExpectationsDeclared() {
 
 	/**
 	 * As of 5.0.3 subclasses should implement this method instead of
-	 * {@link #validateRequestInternal(ClientHttpRequest)} in order to match the
+	 * {@code #validateRequestInternal(ClientHttpRequest)} in order to match the
 	 * request to an expectation, leaving the call to create the response as a separate step
 	 * (to be invoked by this class).
 	 * @param request the current request

spring-tx/src/main/java/org/springframework/transaction/annotation/Isolation.java

@@ -70,7 +70,7 @@ public enum Isolation {
 	/**
 	 * A constant indicating that dirty reads, non-repeatable reads, and phantom
 	 * reads are prevented.
-	 * <p>This level includes the prohibitions in {@link #ISOLATION_REPEATABLE_READ}
+	 * <p>This level includes the prohibitions in {@link #REPEATABLE_READ}
 	 * and further prohibits the situation where one transaction reads all rows that
 	 * satisfy a {@code WHERE} condition, a second transaction inserts a row
 	 * that satisfies that {@code WHERE} condition, and the first transaction

spring-web/src/main/java/org/springframework/http/client/support/HttpAccessor.java

@@ -66,7 +66,7 @@ public abstract class HttpAccessor {
 	 * Configure the Apache HttpComponents or OkHttp request factory to enable PATCH.</b>
 	 * @see #createRequest(URI, HttpMethod)
 	 * @see SimpleClientHttpRequestFactory
-	 * @see org.springframework.http.client.HttpComponentsAsyncClientHttpRequestFactory
+	 * @see org.springframework.http.client.HttpComponentsClientHttpRequestFactory
 	 * @see org.springframework.http.client.OkHttp3ClientHttpRequestFactory
 	 */
 	public void setRequestFactory(ClientHttpRequestFactory requestFactory) {

spring-web/src/main/java/org/springframework/web/client/RestOperations.java

@@ -383,7 +383,7 @@ <T> ResponseEntity<T> postForEntity(URI url, @Nullable Object request, Class<T>
 	 * @since 4.3.5
 	 * @see HttpEntity
 	 * @see RestTemplate#setRequestFactory
-	 * @see org.springframework.http.client.HttpComponentsAsyncClientHttpRequestFactory
+	 * @see org.springframework.http.client.HttpComponentsClientHttpRequestFactory
 	 * @see org.springframework.http.client.OkHttp3ClientHttpRequestFactory
 	 */
 	@Nullable
@@ -406,7 +406,7 @@ <T> T patchForObject(String url, @Nullable Object request, Class<T> responseType
 	 * @since 4.3.5
 	 * @see HttpEntity
 	 * @see RestTemplate#setRequestFactory
-	 * @see org.springframework.http.client.HttpComponentsAsyncClientHttpRequestFactory
+	 * @see org.springframework.http.client.HttpComponentsClientHttpRequestFactory
 	 * @see org.springframework.http.client.OkHttp3ClientHttpRequestFactory
 	 */
 	@Nullable
@@ -427,7 +427,7 @@ <T> T patchForObject(String url, @Nullable Object request, Class<T> responseType
 	 * @since 4.3.5
 	 * @see HttpEntity
 	 * @see RestTemplate#setRequestFactory
-	 * @see org.springframework.http.client.HttpComponentsAsyncClientHttpRequestFactory
+	 * @see org.springframework.http.client.HttpComponentsClientHttpRequestFactory
 	 * @see org.springframework.http.client.OkHttp3ClientHttpRequestFactory
 	 */
 	@Nullable