From eabb846d07abf7676224dd74e08bedf36ba6b899 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Simon=20Basl=C3=A9?= Date: Thu, 4 May 2023 18:20:43 +0200 Subject: [PATCH 1/2] 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 --- framework-docs/framework-docs.gradle | 2 +- framework-docs/modules/ROOT/pages/appendix.adoc | 2 +- gradle/spring-module.gradle | 7 +++++-- .../java/org/springframework/cglib/core/CodeEmitter.java | 1 - .../org/springframework/cglib/proxy/InterfaceMaker.java | 2 +- .../org/springframework/cglib/proxy/InvocationHandler.java | 2 +- .../cglib/transform/impl/UndeclaredThrowableStrategy.java | 2 +- .../org/springframework/cglib/util/ParallelSorter.java | 4 +--- .../java/org/springframework/core/SpringProperties.java | 2 +- .../jdbc/datasource/DriverManagerDataSource.java | 6 +++--- .../test/context/CacheAwareContextLoaderDelegate.java | 1 - .../test/context/TestContextAnnotationUtils.java | 2 +- .../context/support/AbstractTestContextBootstrapper.java | 6 +++--- .../org/springframework/test/util/TestSocketUtils.java | 2 +- .../test/web/client/AbstractRequestExpectationManager.java | 2 +- .../springframework/transaction/annotation/Isolation.java | 2 +- .../springframework/http/client/support/HttpAccessor.java | 2 +- .../org/springframework/web/client/RestOperations.java | 6 +++--- 18 files changed, 26 insertions(+), 27 deletions(-) diff --git a/framework-docs/framework-docs.gradle b/framework-docs/framework-docs.gradle index 47be5520b24..5a0c3bec975 100644 --- a/framework-docs/framework-docs.gradle +++ b/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 -> diff --git a/framework-docs/modules/ROOT/pages/appendix.adoc b/framework-docs/modules/ROOT/pages/appendix.adoc index c25f35e2de7..c131e439ef5 100644 --- a/framework-docs/modules/ROOT/pages/appendix.adoc +++ b/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` diff --git a/gradle/spring-module.gradle b/gradle/spring-module.gradle index 64efe91661e..130c00fe622 100644 --- a/gradle/spring-module.gradle +++ b/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 } diff --git a/spring-core/src/main/java/org/springframework/cglib/core/CodeEmitter.java b/spring-core/src/main/java/org/springframework/cglib/core/CodeEmitter.java index a7080055a63..35181c5d894 100644 --- a/spring-core/src/main/java/org/springframework/cglib/core/CodeEmitter.java +++ b/spring-core/src/main/java/org/springframework/cglib/core/CodeEmitter.java @@ -737,7 +737,6 @@ public class CodeEmitter extends LocalVariablesSorter { * 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; diff --git a/spring-core/src/main/java/org/springframework/cglib/proxy/InterfaceMaker.java b/spring-core/src/main/java/org/springframework/cglib/proxy/InterfaceMaker.java index 9ed15417a31..b1a886aee7a 100644 --- a/spring-core/src/main/java/org/springframework/cglib/proxy/InterfaceMaker.java +++ b/spring-core/src/main/java/org/springframework/cglib/proxy/InterfaceMaker.java @@ -74,7 +74,7 @@ public class InterfaceMaker extends AbstractClassGenerator * 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. getClass, equals, hashCode). - * @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(); diff --git a/spring-core/src/main/java/org/springframework/cglib/proxy/InvocationHandler.java b/spring-core/src/main/java/org/springframework/cglib/proxy/InvocationHandler.java index cf0a35477f3..a2f82fd2863 100644 --- a/spring-core/src/main/java/org/springframework/cglib/proxy/InvocationHandler.java +++ b/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; diff --git a/spring-core/src/main/java/org/springframework/cglib/transform/impl/UndeclaredThrowableStrategy.java b/spring-core/src/main/java/org/springframework/cglib/transform/impl/UndeclaredThrowableStrategy.java index 02667752f5d..f055d20f674 100644 --- a/spring-core/src/main/java/org/springframework/cglib/transform/impl/UndeclaredThrowableStrategy.java +++ b/spring-core/src/main/java/org/springframework/cglib/transform/impl/UndeclaredThrowableStrategy.java @@ -25,7 +25,7 @@ import org.springframework.cglib.transform.MethodFilterTransformer; 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. */ diff --git a/spring-core/src/main/java/org/springframework/cglib/util/ParallelSorter.java b/spring-core/src/main/java/org/springframework/cglib/util/ParallelSorter.java index 13241044bcd..11cdf02d822 100644 --- a/spring-core/src/main/java/org/springframework/cglib/util/ParallelSorter.java +++ b/spring-core/src/main/java/org/springframework/cglib/util/ParallelSorter.java @@ -64,7 +64,6 @@ abstract public class ParallelSorter extends SorterTemplate { * @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 @@ abstract public class ParallelSorter extends SorterTemplate { /** * 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); diff --git a/spring-core/src/main/java/org/springframework/core/SpringProperties.java b/spring-core/src/main/java/org/springframework/core/SpringProperties.java index 7b15827d270..06916b882df 100644 --- a/spring-core/src/main/java/org/springframework/core/SpringProperties.java +++ b/spring-core/src/main/java/org/springframework/core/SpringProperties.java @@ -38,7 +38,7 @@ import org.springframework.lang.Nullable; * * @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 diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/datasource/DriverManagerDataSource.java b/spring-jdbc/src/main/java/org/springframework/jdbc/datasource/DriverManagerDataSource.java index 8149efb3af7..e6335987df8 100644 --- a/spring-jdbc/src/main/java/org/springframework/jdbc/datasource/DriverManagerDataSource.java +++ b/spring-jdbc/src/main/java/org/springframework/jdbc/datasource/DriverManagerDataSource.java @@ -48,9 +48,9 @@ import org.springframework.util.ClassUtils; * 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 Simple-JNDI, + * or switch the bean definition to a local DataSource (which is simpler and thus recommended). * *

This {@code DriverManagerDataSource} class was originally designed alongside * Apache Commons DBCP diff --git a/spring-test/src/main/java/org/springframework/test/context/CacheAwareContextLoaderDelegate.java b/spring-test/src/main/java/org/springframework/test/context/CacheAwareContextLoaderDelegate.java index 0a5827713ae..0cde8b93e6d 100644 --- a/spring-test/src/main/java/org/springframework/test/context/CacheAwareContextLoaderDelegate.java +++ b/spring-test/src/main/java/org/springframework/test/context/CacheAwareContextLoaderDelegate.java @@ -81,7 +81,6 @@ public interface CacheAwareContextLoaderDelegate { * the application context * @see #isContextLoaded * @see #closeContext - * @see #setContextFailureProcessor */ ApplicationContext loadContext(MergedContextConfiguration mergedContextConfiguration); diff --git a/spring-test/src/main/java/org/springframework/test/context/TestContextAnnotationUtils.java b/spring-test/src/main/java/org/springframework/test/context/TestContextAnnotationUtils.java index 3ac913d5f7e..4f695e1b6fc 100644 --- a/spring-test/src/main/java/org/springframework/test/context/TestContextAnnotationUtils.java +++ b/spring-test/src/main/java/org/springframework/test/context/TestContextAnnotationUtils.java @@ -66,7 +66,7 @@ import org.springframework.util.ObjectUtils; * 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 diff --git a/spring-test/src/main/java/org/springframework/test/context/support/AbstractTestContextBootstrapper.java b/spring-test/src/main/java/org/springframework/test/context/support/AbstractTestContextBootstrapper.java index ba0855ff5d7..b03d224ddfd 100644 --- a/spring-test/src/main/java/org/springframework/test/context/support/AbstractTestContextBootstrapper.java +++ b/spring-test/src/main/java/org/springframework/test/context/support/AbstractTestContextBootstrapper.java @@ -494,13 +494,13 @@ public abstract class AbstractTestContextBootstrapper implements TestContextBoot * interaction with the {@code ContextCache}. *

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. *

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(); diff --git a/spring-test/src/main/java/org/springframework/test/util/TestSocketUtils.java b/spring-test/src/main/java/org/springframework/test/util/TestSocketUtils.java index dbf8e477fe9..9c192b7103d 100644 --- a/spring-test/src/main/java/org/springframework/test/util/TestSocketUtils.java +++ b/spring-test/src/main/java/org/springframework/test/util/TestSocketUtils.java @@ -28,7 +28,7 @@ import org.springframework.util.Assert; * Simple utility for finding available TCP ports on {@code localhost} for use in * integration testing scenarios. * - *

This is a limited form of {@link org.springframework.util.SocketUtils} which + *

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. * diff --git a/spring-test/src/main/java/org/springframework/test/web/client/AbstractRequestExpectationManager.java b/spring-test/src/main/java/org/springframework/test/web/client/AbstractRequestExpectationManager.java index 99658b13a8e..654ff3e6101 100644 --- a/spring-test/src/main/java/org/springframework/test/web/client/AbstractRequestExpectationManager.java +++ b/spring-test/src/main/java/org/springframework/test/web/client/AbstractRequestExpectationManager.java @@ -110,7 +110,7 @@ public abstract class AbstractRequestExpectationManager implements RequestExpect /** * 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 diff --git a/spring-tx/src/main/java/org/springframework/transaction/annotation/Isolation.java b/spring-tx/src/main/java/org/springframework/transaction/annotation/Isolation.java index 5982d8bfabc..15e166f021d 100644 --- a/spring-tx/src/main/java/org/springframework/transaction/annotation/Isolation.java +++ b/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. - *

This level includes the prohibitions in {@link #ISOLATION_REPEATABLE_READ} + *

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 diff --git a/spring-web/src/main/java/org/springframework/http/client/support/HttpAccessor.java b/spring-web/src/main/java/org/springframework/http/client/support/HttpAccessor.java index e2d59b63470..1a1a1c52cbc 100644 --- a/spring-web/src/main/java/org/springframework/http/client/support/HttpAccessor.java +++ b/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. * @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) { diff --git a/spring-web/src/main/java/org/springframework/web/client/RestOperations.java b/spring-web/src/main/java/org/springframework/web/client/RestOperations.java index f25c4f2f895..d3420598055 100644 --- a/spring-web/src/main/java/org/springframework/web/client/RestOperations.java +++ b/spring-web/src/main/java/org/springframework/web/client/RestOperations.java @@ -383,7 +383,7 @@ public interface RestOperations { * @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 @@ public interface RestOperations { * @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 @@ public interface RestOperations { * @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 From 1721e42988425b7c88e8dca068076a68ccd26762 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Simon=20Basl=C3=A9?= Date: Thu, 11 May 2023 16:51:28 +0200 Subject: [PATCH 2/2] Remove JBossAS catch-all javadoc external link This commit removes the JBoss Application Server external javadoc link, which covers too many packages and can thus problematically take precedence for said packages and lead to dead links. It is replaced by Hibernate javadocs for `org.hibernate.*` packages, JakartaEE and jsr305 for annotations. We lose a limited number of links around org.xnio classes and Hibernate-and-JTA-related classes, as a trade-off. See gh-30455 See gh-30428 --- build.gradle | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/build.gradle b/build.gradle index 534bcc8f77d..3e6b0c1fc54 100644 --- a/build.gradle +++ b/build.gradle @@ -115,10 +115,10 @@ configure([rootProject] + javaProjects) { project -> ext.javadocLinks = [ "https://docs.oracle.com/en/java/javase/17/docs/api/", "https://jakarta.ee/specifications/platform/9/apidocs/", - "https://docs.oracle.com/cd/E13222_01/wls/docs90/javadocs/", // CommonJ - "https://www.ibm.com/docs/api/v1/content/SSEQTP_8.5.5/com.ibm.websphere.javadoc.doc/web/apidocs/", - "https://docs.jboss.org/jbossas/javadoc/4.0.5/connector/", - "https://docs.jboss.org/jbossas/javadoc/7.1.2.Final/", + "https://docs.oracle.com/cd/E13222_01/wls/docs90/javadocs/", // CommonJ and weblogic.* packages + "https://www.ibm.com/docs/api/v1/content/SSEQTP_8.5.5/com.ibm.websphere.javadoc.doc/web/apidocs/", // com.ibm.* + "https://docs.jboss.org/jbossas/javadoc/4.0.5/connector/", // org.jboss.resource.* + "https://docs.jboss.org/hibernate/orm/5.6/javadocs/", "https://www.eclipse.org/aspectj/doc/released/aspectj5rt-api/", "https://www.quartz-scheduler.org/api/2.3.0/", "https://www.javadoc.io/doc/com.fasterxml.jackson.core/jackson-core/2.14.1/", @@ -134,11 +134,9 @@ configure([rootProject] + javaProjects) { project -> "https://www.reactive-streams.org/reactive-streams-1.0.3-javadoc/", "https://javadoc.io/static/io.rsocket/rsocket-core/1.1.1/", "https://r2dbc.io/spec/1.0.0.RELEASE/api/", - // The external Javadoc link for JSR 305 must come last to ensure that types from - // JSR 250 (such as @PostConstruct) are still supported. This is due to the fact - // that JSR 250 and JSR 305 both define types in javax.annotation, which results - // in a split package, and the javadoc tool does not support split packages - // across multiple external Javadoc sites. + // Previously there could be a split-package issue between JSR250 and JSR305 javax.annotation packages, + // but since 6.0 JSR 250 annotations such as @Resource and @PostConstruct have been replaced by their + // JakartaEE equivalents in the jakarta.annotation package. "https://www.javadoc.io/doc/com.google.code.findbugs/jsr305/3.0.2/" ] as String[] }