Merge branch '6.0.x' (javadoc changes)

2023-05-16 15:05:42 +02:00 · 2023-05-16 15:05:42 +02:00 · f5bc084ce2
parent d86cfc949d 1721e42988
commit f5bc084ce2
19 changed files with 33 additions and 36 deletions
--- a/build.gradle
+++ b/build.gradle
@ -86,10 +86,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/",
@ -105,11 +105,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[]
 }
--- 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 ->
--- 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`
--- 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
 }
--- 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;
--- 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. <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();
--- 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;

--- 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.
 */
--- 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);
--- 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
--- 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 <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>
--- 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);

--- 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
--- 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}.
 	 * <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();
--- 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.
 *
- * <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.
 *
--- 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
--- 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.
-	 * <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
--- 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.</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) {
--- 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