Skip to content

Commit eabb846

Browse files
committed
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
1 parent 280b0de commit eabb846

File tree

18 files changed

+26
-27
lines changed

18 files changed

+26
-27
lines changed

framework-docs/framework-docs.gradle

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@ task api(type: Javadoc) {
104104
overview = "framework-docs/src/docs/api/overview.html"
105105
splitIndex = true
106106
links(project.ext.javadocLinks)
107-
addBooleanOption('Xdoclint:syntax', true) // only check syntax with doclint
107+
addBooleanOption('Xdoclint:syntax,reference', true) // only check syntax and reference with doclint
108108
addBooleanOption('Werror', true) // fail build on Javadoc warnings
109109
}
110110
source moduleProjects.collect { project ->

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ The following table lists all currently supported Spring properties.
2525
| `spring.beaninfo.ignore`
2626
| Instructs Spring to use the `Introspector.IGNORE_ALL_BEANINFO` mode when calling the
2727
JavaBeans `Introspector`. See
28-
{api-spring-framework}++/beans/CachedIntrospectionResults.html#IGNORE_BEANINFO_PROPERTY_NAME++[`CachedIntrospectionResults`]
28+
{api-spring-framework}++/beans/StandardBeanInfoFactory.html#IGNORE_BEANINFO_PROPERTY_NAME++[`CachedIntrospectionResults`]
2929
for details.
3030

3131
| `spring.expression.compiler.mode`

gradle/spring-module.gradle

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,10 +72,13 @@ javadoc {
7272
options.header = project.name
7373
options.use = true
7474
options.links(project.ext.javadocLinks)
75-
options.addStringOption("Xdoclint:none", "-quiet")
75+
// Check for syntax during linting. 'none' doesn't seem to work in suppressing
76+
// all linting warnings all the time (see/link references most notably).
77+
options.addStringOption("Xdoclint:syntax", "-quiet")
7678

7779
// Suppress warnings due to cross-module @see and @link references.
78-
// Note that global 'api' task does display all warnings.
80+
// Note that global 'api' task does display all warnings, and
81+
// checks for 'reference' on top of 'syntax'.
7982
logging.captureStandardError LogLevel.INFO
8083
logging.captureStandardOutput LogLevel.INFO // suppress "## warnings" message
8184
}

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

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -737,7 +737,6 @@ public void box(Type type) {
737737
* on the top of the stack with the unwrapped (primitive)
738738
* equivalent. For example, Character -> char.
739739
* @param type the class indicating the desired type of the top stack value
740-
* @return true if the value was unboxed
741740
*/
742741
public void unbox(Type type) {
743742
Type t = Constants.TYPE_NUMBER;

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ public void add(Method method) {
7474
* Add all the public methods in the specified class.
7575
* Methods from superclasses are included, except for methods declared in the base
7676
* Object class (e.g. <code>getClass</code>, <code>equals</code>, <code>hashCode</code>).
77-
* @param class the class containing the methods to add to the interface
77+
* @param clazz the class containing the methods to add to the interface
7878
*/
7979
public void add(Class clazz) {
8080
Method[] methods = clazz.getMethods();

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ public interface InvocationHandler
2828
extends Callback
2929
{
3030
/**
31-
* @see java.lang.reflect.InvocationHandler#invoke(java.lang.Object, java.lang.reflect.Method, java.lang.Object)
31+
* @see java.lang.reflect.InvocationHandler#invoke(java.lang.Object, java.lang.reflect.Method, java.lang.Object[])
3232
*/
3333
public Object invoke(Object proxy, Method method, Object[] args) throws Throwable;
3434

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@
2525
import org.springframework.cglib.transform.TransformingClassGenerator;
2626

2727
/**
28-
* A {@link GeneratorStrategy} suitable for use with {@link org.springframework.cglib.Enhancer} which
28+
* A {@link GeneratorStrategy} suitable for use with {@link org.springframework.cglib.proxy.Enhancer} which
2929
* causes all undeclared exceptions thrown from within a proxied method to be wrapped
3030
* in an alternative exception of your choice.
3131
*/

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

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,6 @@ protected ParallelSorter() {
6464
* @param arrays An array of arrays to sort. The arrays may be a mix
6565
* of primitive and non-primitive types, but should all be the same
6666
* length.
67-
* @param loader ClassLoader for generated class, uses "current" if null
6867
*/
6968
public static ParallelSorter create(Object[] arrays) {
7069
Generator gen = new Generator();
@@ -135,8 +134,7 @@ public void mergeSort(int index, int lo, int hi) {
135134
/**
136135
* Sort the arrays using an in-place merge sort.
137136
* @param index array (column) to sort by
138-
* @param lo starting array index (row), inclusive
139-
* @param hi ending array index (row), exclusive
137+
* @param cmp Comparator to use if the specified column is non-primitive
140138
*/
141139
public void mergeSort(int index, Comparator cmp) {
142140
mergeSort(index, 0, len(), cmp);

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@
3838
*
3939
* @author Juergen Hoeller
4040
* @since 3.2.7
41-
* @see org.springframework.beans.CachedIntrospectionResults#IGNORE_BEANINFO_PROPERTY_NAME
41+
* @see org.springframework.beans.StandardBeanInfoFactory#IGNORE_BEANINFO_PROPERTY_NAME
4242
* @see org.springframework.context.index.CandidateComponentsIndexLoader#IGNORE_INDEX
4343
* @see org.springframework.core.env.AbstractEnvironment#IGNORE_GETENV_PROPERTY_NAME
4444
* @see org.springframework.expression.spel.SpelParserConfiguration#SPRING_EXPRESSION_COMPILER_MODE_PROPERTY_NAME

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

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

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

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,6 @@ default boolean isContextLoaded(MergedContextConfiguration mergedContextConfigur
8181
* the application context
8282
* @see #isContextLoaded
8383
* @see #closeContext
84-
* @see #setContextFailureProcessor
8584
*/
8685
ApplicationContext loadContext(MergedContextConfiguration mergedContextConfiguration);
8786

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@
6666
* example, {@link ContextConfiguration#inheritLocations}.
6767
*
6868
* @author Sam Brannen
69-
* @since 5.3, though originally since 4.0 as {@link org.springframework.test.util.MetaAnnotationUtils}
69+
* @since 5.3, though originally since 4.0 as {@code org.springframework.test.util.MetaAnnotationUtils}
7070
* @see AnnotationUtils
7171
* @see AnnotatedElementUtils
7272
* @see AnnotationDescriptor

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -494,13 +494,13 @@ else if (logger.isDebugEnabled()) {
494494
* interaction with the {@code ContextCache}.
495495
* <p>The default implementation delegates to
496496
* {@code getBootstrapContext().getCacheAwareContextLoaderDelegate()} and
497-
* supplies the returned delegate the configured
498-
* {@link #getApplicationContextFailureProcessor() ApplicationContextFailureProcessor}.
497+
* the default one will load {@link org.springframework.test.context.ApplicationContextFailureProcessor}
498+
* via the service loading mechanism.
499499
* <p>Concrete subclasses may choose to override this method to return a custom
500500
* {@code CacheAwareContextLoaderDelegate} implementation with custom
501501
* {@link org.springframework.test.context.cache.ContextCache ContextCache} support.
502502
* @return the context loader delegate (never {@code null})
503-
* @see #getApplicationContextFailureProcessor()
503+
* @see org.springframework.test.context.ApplicationContextFailureProcessor
504504
*/
505505
protected CacheAwareContextLoaderDelegate getCacheAwareContextLoaderDelegate() {
506506
return getBootstrapContext().getCacheAwareContextLoaderDelegate();

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@
2828
* Simple utility for finding available TCP ports on {@code localhost} for use in
2929
* integration testing scenarios.
3030
*
31-
* <p>This is a limited form of {@link org.springframework.util.SocketUtils} which
31+
* <p>This is a limited form of {@code org.springframework.util.SocketUtils}, which
3232
* has been deprecated since Spring Framework 5.3.16 and removed in Spring
3333
* Framework 6.0.
3434
*

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@ protected void afterExpectationsDeclared() {
110110

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

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@ public enum Isolation {
7070
/**
7171
* A constant indicating that dirty reads, non-repeatable reads, and phantom
7272
* reads are prevented.
73-
* <p>This level includes the prohibitions in {@link #ISOLATION_REPEATABLE_READ}
73+
* <p>This level includes the prohibitions in {@link #REPEATABLE_READ}
7474
* and further prohibits the situation where one transaction reads all rows that
7575
* satisfy a {@code WHERE} condition, a second transaction inserts a row
7676
* that satisfies that {@code WHERE} condition, and the first transaction

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ public abstract class HttpAccessor {
6666
* Configure the Apache HttpComponents or OkHttp request factory to enable PATCH.</b>
6767
* @see #createRequest(URI, HttpMethod)
6868
* @see SimpleClientHttpRequestFactory
69-
* @see org.springframework.http.client.HttpComponentsAsyncClientHttpRequestFactory
69+
* @see org.springframework.http.client.HttpComponentsClientHttpRequestFactory
7070
* @see org.springframework.http.client.OkHttp3ClientHttpRequestFactory
7171
*/
7272
public void setRequestFactory(ClientHttpRequestFactory requestFactory) {

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -383,7 +383,7 @@ <T> ResponseEntity<T> postForEntity(URI url, @Nullable Object request, Class<T>
383383
* @since 4.3.5
384384
* @see HttpEntity
385385
* @see RestTemplate#setRequestFactory
386-
* @see org.springframework.http.client.HttpComponentsAsyncClientHttpRequestFactory
386+
* @see org.springframework.http.client.HttpComponentsClientHttpRequestFactory
387387
* @see org.springframework.http.client.OkHttp3ClientHttpRequestFactory
388388
*/
389389
@Nullable
@@ -406,7 +406,7 @@ <T> T patchForObject(String url, @Nullable Object request, Class<T> responseType
406406
* @since 4.3.5
407407
* @see HttpEntity
408408
* @see RestTemplate#setRequestFactory
409-
* @see org.springframework.http.client.HttpComponentsAsyncClientHttpRequestFactory
409+
* @see org.springframework.http.client.HttpComponentsClientHttpRequestFactory
410410
* @see org.springframework.http.client.OkHttp3ClientHttpRequestFactory
411411
*/
412412
@Nullable
@@ -427,7 +427,7 @@ <T> T patchForObject(String url, @Nullable Object request, Class<T> responseType
427427
* @since 4.3.5
428428
* @see HttpEntity
429429
* @see RestTemplate#setRequestFactory
430-
* @see org.springframework.http.client.HttpComponentsAsyncClientHttpRequestFactory
430+
* @see org.springframework.http.client.HttpComponentsClientHttpRequestFactory
431431
* @see org.springframework.http.client.OkHttp3ClientHttpRequestFactory
432432
*/
433433
@Nullable

0 commit comments

Comments
 (0)