links to https://docs.jboss.org/jbossas/javadoc/7.1.2.Final/javax/annotation/Nonnull.html:
Comment From: sbrannen
For clarity, the link behind the @Nonnull annotation displayed in the generated Javadoc for Spring's @org.springframework.lang.NonNull annotation links to a non-existing Javadoc page at JBoss instead of an appropriate Javadoc Web site for javax.annotation.Nonnull.
Comment From: salmansharifov
Hi. Can I take this issue?
Comment From: simonbasle
@salmansharifov I've started investigating this in parallel of other javadoc changes I am doing in #30428 feel free to let me know if you have any particular insight, though.
Comment From: sbrannen
I just realized that I already investigated this once.
Thus, this is effectively a...
- duplicate of #27904
So, @simonbasle, feel free to close it as a duplicate... or keep it open in case you want to investigate it further. I'll leave it up to you. 😉
Comment From: simonbasle
@sbrannen I think that now that we depend on jakarta.annotations and not javax.annotation, there is a way out :)
here is my full investigation on this issue:
Looking at the docs of previous versions (5.3.x) the link under the @Nonnull annotation would also be invalid, but due to pointing to the JDK javadocs (which also contain elements in package javax.annotation => JSR 250 @Resource, @PostConstruct, ...)
So in 5.3.x we have several external links sources that cover the javax.annotation packages:
- JDK docs (JSR 250)
- JavaEE docs (JSR 250)
- JBoss Application Server (which is a bit of a catch-all, including JSR 250)
- javadoc.io findbugs:jsr305-javadoc.jar (the only one that contains @Nonnull)
A comment in the build file hints that under Java 8 the Javadoc will not 100% deal with split packages but will prioritize the one at the top. It puts the JSR 305 link at the bottom in order to prioritize linking to JSR 250 annotations like @PostConstruct.
In this maintenance branch the conflict is a bit unresolvable due to the two JSRs sharing the package root so this is the best workaround.
But in newer versions of Java, JDK docs don't contain JSR 250 annotations / javax.annotation package.
Additionally, there is no JavaEE docs anymore and the JakartaEE namespace change puts the JSR 250-equivalent annotations in the jakarta.annotation package instead.
In fact, pure JSR 250 annotations are not used in newer Spring Framework javadocs at all, but the JBossAS link is still there.
This leads to the JBossAS link taking precedence for javax.annotation package.
This JBossAS doc external link is problematic because it covers a lot of packages. I've compared the generated Spring API docs with and without this particular link in the 6.0.x branch to find diffs in hrefs and it appears it is actually relevant for 2 things:
- hibernate <a href="https://docs.jboss.org/jbossas/javadoc/7.1.2.Final/org/hibernate/">
- xnio <a href="https://docs.jboss.org/jbossas/javadoc/7.1.2.Final/org/xnio/Xnio.html"
I couldn't find a satisfactory javadoc source for the later, but for hibernate this could be replaced by https://docs.jboss.org/hibernate/orm/5.6/javadocs/.
We could give up on linking to xnio classes, and drop the JBossAS external link entirely to decrease the chances of split package issues like this one. As a result: - hibernate classes would get links from the Hibernate external link - JSR-250-equivalent classes would get links from the JakartaEE external link - JSR 305 classes would get links from the findbugs/jsr305-javadoc.jar through javadoc.io external link - xnio classes would not be linked anymore
Comment From: simonbasle
superseded by #30428 (see commit reference in the timeline) won't be backported to 5.3.x