Link for `@javax.annotation.Nonnull` is wrong in Javadoc for Spring's `@NonNull`

[ullenboom]

links to https://docs.jboss.org/jbossas/javadoc/7.1.2.Final/javax/annotation/Nonnull.html:

[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.

[salmansharifov]

Hi. Can I take this issue?

[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.

[sbrannen]

I just realized that I already investigated this once.

Thus, this is effectively a...

• duplicate of Fix Javadoc links to JSR 305 annotations #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. 😉

[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

[simonbasle]

superseded by #30428 (see commit reference in the timeline)
won't be backported to 5.3.x