Skip to content

Commit

Permalink
Fix Javadoc links to JSR 305 annotations where feasible
Browse files Browse the repository at this point in the history
Prior to this commit, we only (indirectly) configured external Javadoc
links for types in the javax.annotation package for JSR 250, since
those types are part of Java 8 SE. However, an external Javadoc link
for types from JSR 305 was not configured.

To address this issue, this commit now configures an external Javadoc
link for JSR 305 types. However, the external Javadoc link for JSR 305
must be configured 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. Instead, the Javadoc tool
iterates over all external links, and the first external site that
claims to support a given package (via the package-list file) wins.

This means:

- Javadoc for JSR 250 annotations is fully supported.
- Javadoc for JSR 305 annotations in the javax.annotation package will
  continue to result in a 404 (page not found) error.
- Javadoc for JSR 305 annotations in the javax.annotation.meta package
  is fully supported.

For Spring Framework 6.0, the Javadoc for JSR 250 types in
jakarta.annotation package is served from the JBoss Application Server
Javadoc site instead of from Oracle's Java SE documentation site, since
JSR 250 annotations are no longer included in Java SE.

Closes gh-27904
  • Loading branch information
sbrannen committed Jan 21, 2022
1 parent 7211912 commit a681d6a
Showing 1 changed file with 7 additions and 1 deletion.
8 changes: 7 additions & 1 deletion build.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -388,7 +388,13 @@ configure([rootProject] + javaProjects) { project ->
// "https://junit.org/junit5/docs/5.8.2/api/",
"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/0.8.5.RELEASE/api/"
"https://r2dbc.io/spec/0.8.5.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.
"https://www.javadoc.io/doc/com.google.code.findbugs/jsr305/3.0.2/"
] as String[]
}

Expand Down

0 comments on commit a681d6a

Please sign in to comment.