Skip to content

Commit f265347

Browse files
committed
Eliminate all Javadoc warnings
- Support external Javadoc links using Gradle's javadoc.options.links - Fix all other Javadoc warnings, such as typos, references to non-existent (or no longer existent) types and members, etc, including changes related to the Quartz 2.0 upgrade (SPR-8275) and adding the HTTP PATCH method (SPR-7985). - Suppress all output for project-level `javadoc` tasks in order to hide false-negative warnings about cross-module @see and @link references (e.g. spring-core having a @see reference to spring-web). Use the `--info` (-i) flag to gradle at any time to see project-level javadoc warnings without running the entire `api` task. e.g. `gradle :spring-core:javadoc -i` - Favor root project level `api` task for detection of legitimate Javadoc warnings. There are now zero Javadoc warnings across the entirety of spring-framework. Goal: keep it that way. - Remove all @link and @see references to types and members that exist only in Servlet <= 2.5 and Hibernate <= 4.0, favoring 3.0+ and 4.0+ respectively. This is necessary because only one version of each of these dependencies can be present on the global `api` javadoc task's classpath. To that end, the `api` task classpath has now been customized to ensure that the Servlet 3 API and Hibernate Core 4 jars have precedence. - SPR-8896 replaced our dependency on aspectjrt with a dependency on aspectjweaver, which is fine from a POM point of view, but causes a spurious warning to be emitted from the ant iajc task that it "cannot find aspectjrt on the classpath" - even though aspectjweaver is perfectly sufficient. In the name of keeping the console quiet, a new `rt` configuration has been added, and aspectjrt added as a dependency to it. In turn, configurations.rt.asPath is appended to the iajc classpath during both compileJava and compileTestJava for spring-aspects. Issue: SPR-10078, SPR-8275, SPR-7985, SPR-8896
1 parent 8f90b48 commit f265347

File tree

72 files changed

+217
-221
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

72 files changed

+217
-221
lines changed

build.gradle

Lines changed: 46 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,28 @@ configure(allprojects) {
4343
testCompile("org.hamcrest:hamcrest-all:1.3")
4444
testCompile("org.easymock:easymock:${easymockVersion}")
4545
}
46+
47+
ext.javadocLinks = [
48+
"http://docs.oracle.com/javase/6/docs/api",
49+
"http://docs.oracle.com/javaee/6/api",
50+
"http://portals.apache.org/pluto/portlet-2.0-apidocs/",
51+
"http://commons.apache.org/lang/api-2.5",
52+
"http://commons.apache.org/codec/apidocs",
53+
"http://docs.jboss.org/jbossas/javadoc/4.0.5/connector",
54+
"http://docs.jboss.org/jbossas/javadoc/7.1.2.Final",
55+
"http://aopalliance.sourceforge.net/doc",
56+
"http://glassfish.java.net/nonav/docs/v3/api",
57+
"http://docs.oracle.com/cd/E13222_01/wls/docs90/javadocs", // commonj
58+
"http://quartz-scheduler.org/api/2.1.5",
59+
"http://www.eclipse.org/aspectj/doc/released/aspectj5rt-api/",
60+
"http://hc.apache.org/httpclient-3.x/apidocs",
61+
"http://fasterxml.github.com/jackson-core/javadoc/2.0.0",
62+
"http://jackson.codehaus.org/1.4.2/javadoc",
63+
"http://pic.dhe.ibm.com/infocenter/wasinfo/v7r0/topic/com.ibm.websphere.javadoc.doc/web/apidocs",
64+
"http://ibatis.apache.org/docs/java/dev",
65+
"http://tiles.apache.org/framework/apidocs",
66+
"http://commons.apache.org/dbcp/api-1.2.2",
67+
] as String[]
4668
}
4769

4870
configure(subprojects) { subproject ->
@@ -64,10 +86,17 @@ configure(subprojects) { subproject ->
6486
}
6587

6688
javadoc {
89+
description = "Generates project-level javadoc for use in -javadoc jar"
90+
6791
options.memberLevel = org.gradle.external.javadoc.JavadocMemberLevel.PROTECTED
6892
options.author = true
6993
options.header = project.name
70-
//options.overview = "${projectDir}/src/main/java/overview.html"
94+
options.links(project.ext.javadocLinks)
95+
96+
// suppress warnings due to cross-module @see and @link references;
97+
// note that global 'api' task does display all warnings.
98+
logging.captureStandardError LogLevel.INFO
99+
logging.captureStandardOutput LogLevel.INFO // suppress "## warnings" message
71100
}
72101

73102
task sourcesJar(type: Jar, dependsOn:classes) {
@@ -641,6 +670,7 @@ project("spring-aspects") {
641670
provided("javax.persistence:persistence-api:1.0")
642671
testCompile("javax.mail:mail:1.4")
643672
ajc("org.aspectj:aspectjtools:${aspectjVersion}")
673+
rt("org.aspectj:aspectjrt:${aspectjVersion}")
644674
compile("org.aspectj:aspectjweaver:${aspectjVersion}")
645675
testCompile(project(":spring-core")) // for CodeStyleAspect
646676
compile(project(":spring-beans")) // for "p" namespace visibility
@@ -677,8 +707,6 @@ configure(rootProject) {
677707
configurations.archives.artifacts.clear()
678708

679709
dependencies { // for integration tests
680-
compile gradleApi()
681-
groovy localGroovy()
682710
testCompile(project(":spring-core"))
683711
testCompile(project(":spring-beans"))
684712
testCompile(project(":spring-aop"))
@@ -703,22 +731,30 @@ configure(rootProject) {
703731
group = "Documentation"
704732
description = "Generates aggregated Javadoc API documentation."
705733
title = "${rootProject.description} ${version} API"
734+
706735
options.memberLevel = org.gradle.external.javadoc.JavadocMemberLevel.PROTECTED
707736
options.author = true
708737
options.header = rootProject.description
709738
options.overview = "src/api/overview.html"
710739
options.splitIndex = true
711-
options.links(
712-
"http://docs.jboss.org/jbossas/javadoc/4.0.5/connector"
713-
)
740+
options.links(project.ext.javadocLinks)
741+
714742
source subprojects.collect { project ->
715743
project.sourceSets.main.allJava
716744
}
717-
destinationDir = new File(buildDir, "api")
718-
classpath = files(subprojects.collect { project ->
719-
project.sourceSets.main.compileClasspath
720-
})
745+
746+
classpath = files(
747+
// ensure servlet 3.x and Hibernate 4.x have precedence on the Javadoc
748+
// classpath over their respective 2.5 and 3.x variants
749+
project(":spring-webmvc").sourceSets.main.compileClasspath.files.find { it =~ "servlet-api" },
750+
rootProject.sourceSets.test.compileClasspath.files.find { it =~ "hibernate-core" },
751+
// ensure the javadoc process can resolve types compiled from .aj sources
752+
project(":spring-aspects").sourceSets.main.output
753+
)
754+
classpath += files(subprojects.collect { it.sourceSets.main.compileClasspath })
755+
721756
maxMemory = "1024m"
757+
destinationDir = new File(buildDir, "api")
722758
}
723759

724760
task docsZip(type: Zip) {

spring-aop/src/main/java/org/springframework/aop/aspectj/annotation/AspectJProxyFactory.java

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright 2002-2009 the original author or authors.
2+
* Copyright 2002-2012 the original author or authors.
33
*
44
* Licensed under the Apache License, Version 2.0 (the "License");
55
* you may not use this file except in compliance with the License.
@@ -114,7 +114,7 @@ public void addAspect(Class aspectClass) {
114114
/**
115115
* Add all {@link Advisor Advisors} from the supplied {@link MetadataAwareAspectInstanceFactory}
116116
* to the current chain. Exposes any special purpose {@link Advisor Advisors} if needed.
117-
* @see #makeAdvisorChainAspectJCapableIfNecessary()
117+
* @see AspectJProxyUtils#makeAdvisorChainAspectJCapableIfNecessary(List)
118118
*/
119119
private void addAdvisorsFromAspectInstanceFactory(MetadataAwareAspectInstanceFactory instanceFactory) {
120120
List<Advisor> advisors = this.aspectFactory.getAdvisors(instanceFactory);

spring-aop/src/main/java/org/springframework/aop/interceptor/AsyncExecutionAspectSupport.java

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@
3333
/**
3434
* Base class for asynchronous method execution aspects, such as
3535
* {@link org.springframework.scheduling.annotation.AnnotationAsyncExecutionInterceptor}
36-
* or {@link org.springframework.scheduling.aspectj.AnnotationAsyncExecutionAspect}.
36+
* or {@code org.springframework.scheduling.aspectj.AnnotationAsyncExecutionAspect}.
3737
*
3838
* <p>Provides support for <i>executor qualification</i> on a method-by-method basis.
3939
* {@code AsyncExecutionAspectSupport} objects must be constructed with a default {@code
@@ -87,7 +87,7 @@ public void setBeanFactory(BeanFactory beanFactory) throws BeansException {
8787

8888
/**
8989
* Determine the specific executor to use when executing the given method.
90-
* @returns the executor to use (never {@code null})
90+
* @return the executor to use (never {@code null})
9191
*/
9292
protected AsyncTaskExecutor determineAsyncExecutor(Method method) {
9393
if (!this.executors.containsKey(method)) {

spring-aspects/aspects.gradle

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
// compile sources with ajc instead of javac
33

44
configurations {
5+
rt
56
ajc
67
aspects
78
ajInpath
@@ -26,7 +27,7 @@ task compileJava(overwrite: true) {
2627
aspectPath: configurations.aspects.asPath,
2728
inpath: configurations.ajInpath.asPath,
2829
sourceRootCopyFilter: "**/*.java",
29-
classpath: sourceSets.main.runtimeClasspath.asPath) {
30+
classpath: (sourceSets.main.runtimeClasspath + configurations.rt).asPath) {
3031
sourceroots {
3132
sourceSets.main.java.srcDirs.each {
3233
pathelement(location:it.absolutePath)
@@ -55,7 +56,8 @@ task compileTestJava(overwrite: true) {
5556
destDir: outputDir.absolutePath,
5657
aspectPath: jar.archivePath,
5758
inpath: configurations.ajInpath.asPath,
58-
classpath: sourceSets.test.runtimeClasspath.asPath + jar.archivePath) {
59+
classpath: sourceSets.test.runtimeClasspath.asPath + jar.archivePath +
60+
System.getProperty("path.separator") + configurations.rt.asPath) {
5961
sourceroots {
6062
sourceSets.test.java.srcDirs.each {
6163
pathelement(location:it.absolutePath)

spring-aspects/src/main/java/org/springframework/context/annotation/aspectj/SpringConfiguredConfiguration.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@
2323
import org.springframework.context.annotation.Role;
2424

2525
/**
26-
* {@code @Configuration} class that registers an {@link AnnotationBeanConfigurerAspect}
26+
* {@code @Configuration} class that registers an {@code AnnotationBeanConfigurerAspect}
2727
* capable of performing dependency injection services for non-Spring managed objects
2828
* annotated with @{@link org.springframework.beans.factory.annotation.Configurable
2929
* Configurable}.

spring-aspects/src/main/java/org/springframework/mock/staticmock/MockStaticEntityMethods.java

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright 2002-2010 the original author or authors.
2+
* Copyright 2002-2012 the original author or authors.
33
*
44
* Licensed under the Apache License, Version 2.0 (the "License");
55
* you may not use this file except in compliance with the License.
@@ -22,10 +22,10 @@
2222

2323
/**
2424
* Annotation to indicate a test class for whose @Test methods
25-
* static methods on Entity classes should be mocked.
25+
* static methods on Entity classes should be mocked. See
26+
* {@code AbstractMethodMockingControl}.
2627
*
2728
* @author Rod Johnson
28-
* @see AbstractMethodMockingControl
2929
*/
3030
@Retention(RetentionPolicy.RUNTIME)
3131
@Target(ElementType.TYPE)

spring-beans/src/main/java/org/springframework/beans/factory/config/PropertyPlaceholderConfigurer.java

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,8 @@
3737
*
3838
* <p>{@link PropertyPlaceholderConfigurer} is still appropriate for use when:
3939
* <ul>
40-
* <li>the {@link org.springframework.context spring-context} module is not available (i.e., one is using
41-
* Spring's {@code BeanFactory} API as opposed to {@code ApplicationContext}).
40+
* <li>the {@code spring-context} module is not available (i.e., one is using Spring's
41+
* {@code BeanFactory} API as opposed to {@code ApplicationContext}).
4242
* <li>existing configuration makes use of the {@link #setSystemPropertiesMode(int) "systemPropertiesMode"} and/or
4343
* {@link #setSystemPropertiesModeName(String) "systemPropertiesModeName"} properties. Users are encouraged to move
4444
* away from using these settings, and rather configure property source search order through the container's

spring-context-support/src/main/java/org/springframework/scheduling/quartz/SchedulerAccessor.java

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright 2002-2011 the original author or authors.
2+
* Copyright 2002-2012 the original author or authors.
33
*
44
* Licensed under the Apache License, Version 2.0 (the "License");
55
* you may not use this file except in compliance with the License.
@@ -112,21 +112,21 @@ public void setOverwriteExistingJobs(boolean overwriteExistingJobs) {
112112

113113
/**
114114
* Set the location of a Quartz job definition XML file that follows the
115-
* "job_scheduling_data_1_5" XSD. Can be specified to automatically
115+
* "job_scheduling_data_1_5" XSD or better. Can be specified to automatically
116116
* register jobs that are defined in such a file, possibly in addition
117117
* to jobs defined directly on this SchedulerFactoryBean.
118-
* @see org.quartz.xml.JobSchedulingDataProcessor
118+
* @see org.quartz.xml.XmlSchedulingDataProcessor
119119
*/
120120
public void setJobSchedulingDataLocation(String jobSchedulingDataLocation) {
121121
this.jobSchedulingDataLocations = new String[] {jobSchedulingDataLocation};
122122
}
123123

124124
/**
125125
* Set the locations of Quartz job definition XML files that follow the
126-
* "job_scheduling_data_1_5" XSD. Can be specified to automatically
126+
* "job_scheduling_data_1_5" XSD or better. Can be specified to automatically
127127
* register jobs that are defined in such files, possibly in addition
128128
* to jobs defined directly on this SchedulerFactoryBean.
129-
* @see org.quartz.xml.JobSchedulingDataProcessor
129+
* @see org.quartz.xml.XmlSchedulingDataProcessor
130130
*/
131131
public void setJobSchedulingDataLocations(String[] jobSchedulingDataLocations) {
132132
this.jobSchedulingDataLocations = jobSchedulingDataLocations;

spring-context/src/main/java/org/springframework/cache/annotation/CacheEvict.java

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright 2002-2011 the original author or authors.
2+
* Copyright 2002-2012 the original author or authors.
33
*
44
* Licensed under the Apache License, Version 2.0 (the "License");
55
* you may not use this file except in compliance with the License.
@@ -58,8 +58,8 @@
5858
/**
5959
* Whether or not all the entries inside the cache(s) are removed or not. By
6060
* default, only the value under the associated key is removed.
61-
* <p>Note that specifying setting this parameter to true and specifying a
62-
* {@link CacheKey key} is not allowed.
61+
* <p>Note that setting this parameter to {@code true} and specifying a {@link #key()}
62+
* is not allowed.
6363
*/
6464
boolean allEntries() default false;
6565

spring-context/src/main/java/org/springframework/format/datetime/joda/DateTimeFormatterFactory.java

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@
2727

2828
/**
2929
* Factory that creates a Joda {@link DateTimeFormatter}. Formatters will be
30-
* created using the defined {@link #setPattern(String) pattern}, {@link #setIso(ISO) ISO},
30+
* created using the defined {@link #setPattern(String) pattern}, {@link #setIso ISO},
3131
* or {@link #setStyle(String) style} (considered in that order).
3232
*
3333
* @author Phillip Webb
@@ -36,7 +36,7 @@
3636
* @see #createDateTimeFormatter()
3737
* @see #createDateTimeFormatter(DateTimeFormatter)
3838
* @see #setPattern(String)
39-
* @see #setIso(org.springframework.format.annotation.DateTimeFormat.ISO)
39+
* @see #setIso
4040
* @see #setStyle(String)
4141
* @see DateTimeFormatterFactoryBean
4242
*/
@@ -68,7 +68,7 @@ public DateTimeFormatterFactory(String pattern) {
6868

6969
/**
7070
* Create a new {@code DateTimeFormatter} using this factory. If no specific
71-
* {@link #setStyle(String) style}, {@link #setIso(ISO) ISO}, or
71+
* {@link #setStyle(String) style}, {@link #setIso ISO}, or
7272
* {@link #setPattern(String) pattern} have been defined the
7373
* {@link DateTimeFormat#mediumDateTime() medium date time format} will be used.
7474
* @return a new date time formatter
@@ -80,7 +80,7 @@ public DateTimeFormatter createDateTimeFormatter() {
8080

8181
/**
8282
* Create a new {@code DateTimeFormatter} using this factory. If no specific
83-
* {@link #setStyle(String) style}, {@link #setIso(ISO) ISO}, or
83+
* {@link #setStyle(String) style}, {@link #setIso ISO}, or
8484
* {@link #setPattern(String) pattern} have been defined the supplied
8585
* {@code fallbackFormatter} will be used.
8686
* @param fallbackFormatter the fall-back formatter to use when no specific factory

spring-context/src/main/java/org/springframework/jmx/support/WebSphereMBeanServerFactoryBean.java

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,11 +34,12 @@
3434
* This FactoryBean is a direct alternative to {@link MBeanServerFactoryBean},
3535
* which uses standard JMX 1.2 API to access the platform's MBeanServer.
3636
*
37+
* <p>See Javadoc for WebSphere's <a href="http://bit.ly/UzccDt">{@code
38+
* AdminServiceFactory}</a> and <a href="http://bit.ly/TRlX2r">{@code MBeanFactory}</a>.
39+
*
3740
* @author Juergen Hoeller
3841
* @author Rob Harrop
3942
* @since 2.0.3
40-
* @see com.ibm.websphere.management.AdminServiceFactory#getMBeanFactory()
41-
* @see com.ibm.websphere.management.MBeanFactory#getMBeanServer()
4243
* @see javax.management.MBeanServer
4344
* @see MBeanServerFactoryBean
4445
*/

spring-context/src/main/java/org/springframework/scheduling/config/ScheduledTaskRegistrar.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -276,7 +276,7 @@ public boolean hasTasks() {
276276

277277
/**
278278
* Schedule all registered tasks against the underlying {@linkplain
279-
* #setTaskScheduler(TaskScheduler) task scheduler.
279+
* #setTaskScheduler(TaskScheduler) task scheduler}.
280280
*/
281281
public void afterPropertiesSet() {
282282
long now = System.currentTimeMillis();

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -294,7 +294,7 @@ public static Map createApproximateMap(Object map, int initialCapacity) {
294294
/**
295295
* Create the most approximate map for the given map.
296296
* <p>Creates a TreeMap or linked Map for a SortedMap or Map, respectively.
297-
* @param collectionType the desired type of the target Map
297+
* @param mapType the desired type of the target Map
298298
* @param initialCapacity the initial capacity
299299
* @return the new Map instance
300300
* @see java.util.TreeMap

spring-core/src/main/java/org/springframework/core/convert/converter/ConvertingComparator.java

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,6 @@
1818

1919
import java.util.Comparator;
2020
import java.util.Map;
21-
import java.util.Map.Entry;
2221

2322
import org.springframework.core.convert.ConversionService;
2423
import org.springframework.util.Assert;
@@ -44,7 +43,6 @@ public class ConvertingComparator<S, T> implements Comparator<S> {
4443
/**
4544
* Create a new {@link ConvertingComparator} instance.
4645
*
47-
* @param comparator the underlying comparator used to compare the converted values
4846
* @param converter the converter
4947
*/
5048
@SuppressWarnings("unchecked")
@@ -86,8 +84,8 @@ public int compare(S o1, S o2) {
8684
}
8785

8886
/**
89-
* Create a new {@link ConvertingComparator} that compares {@link Map.Entry map
90-
* entries} based on their {@link Map.Entry#getKey() keys}.
87+
* Create a new {@link ConvertingComparator} that compares {@link java.util.Map.Entry
88+
* map * entries} based on their {@link java.util.Map.Entry#getKey() keys}.
9189
*
9290
* @param comparator the underlying comparator used to compare keys
9391
* @return a new {@link ConvertingComparator} instance
@@ -96,15 +94,15 @@ public static <K, V> ConvertingComparator<Map.Entry<K, V>, K> mapEntryKeys(
9694
Comparator<K> comparator) {
9795
return new ConvertingComparator<Map.Entry<K,V>, K>(comparator, new Converter<Map.Entry<K, V>, K>() {
9896

99-
public K convert(Entry<K, V> source) {
97+
public K convert(Map.Entry<K, V> source) {
10098
return source.getKey();
10199
}
102100
});
103101
}
104102

105103
/**
106-
* Create a new {@link ConvertingComparator} that compares {@link Map.Entry map
107-
* entries} based on their {@link Map.Entry#getValue() values}.
104+
* Create a new {@link ConvertingComparator} that compares {@link java.util.Map.Entry
105+
* map entries} based on their {@link java.util.Map.Entry#getValue() values}.
108106
*
109107
* @param comparator the underlying comparator used to compare values
110108
* @return a new {@link ConvertingComparator} instance
@@ -113,7 +111,7 @@ public static <K, V> ConvertingComparator<Map.Entry<K, V>, V> mapEntryValues(
113111
Comparator<V> comparator) {
114112
return new ConvertingComparator<Map.Entry<K,V>, V>(comparator, new Converter<Map.Entry<K, V>, V>() {
115113

116-
public V convert(Entry<K, V> source) {
114+
public V convert(Map.Entry<K, V> source) {
117115
return source.getValue();
118116
}
119117
});

spring-core/src/main/java/org/springframework/core/io/VfsResource.java

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,6 @@
3333
* @author Juergen Hoeller
3434
* @author Costin Leau
3535
* @since 3.0
36-
* @see org.jboss.virtual.VirtualFile
3736
* @see org.jboss.vfs.VirtualFile
3837
*/
3938
public class VfsResource extends AbstractResource {

spring-core/src/main/java/org/springframework/util/ConcurrentReferenceHashMap.java

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -404,8 +404,8 @@ protected final class Segment extends ReentrantLock {
404404

405405
/**
406406
* Array of references indexed using the low order bits from the hash. This
407-
* property should only be set via {@link #setReferences(Reference[])} to ensure
408-
* that the resizeThreshold is maintained.
407+
* property should only be set via {@link #setReferences} to ensure that the
408+
* {@code resizeThreshold} is maintained.
409409
*/
410410
private volatile Reference<K, V>[] references;
411411

0 commit comments

Comments
 (0)