Scaladoc generates incorrect link to JDK API docs with `-release` option

[durban]

Reproduction steps

Scala version: 2.13.11 JDK version: 17.0.7 (OpenJDK) sbt version: 1.9.1

/** Example: [[java.util.concurrent.atomic.AtomicReference]]. */
class Example

build.sbt:

scalaVersion := "2.13.11"

scalacOptions ++= Seq("-release", "11")

Problem

The generated API documentation (with sbt doc) contains an incorrect (dead) link to the AtomicReference apidoc. The incorrect link is https://docs.oracle.com/en/java/javase/17/docs/api/java/util/concurrent/atomic/AtomicReference.html (there is a java.base missing). Also note that the version is 17, regardless of the -release 11 setting.

Without the -release setting, the generated link is correct: https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/atomic/AtomicReference.html.

Originally I've opened an issue here, but it seems the problem is not sbt-plugin specific (probably not even sbt specific).

[Math-ias]

I saw this on the good first issue label. I'd be interested in fixing this bug. I've done a long write-up in the contributors forum. The gist would be ...

• When using -release the class path entry is ct.sym and not a jmod file.
• To fix this we need to get the java module name another way. My first attempt uses reflection.
• I suspect linking the latest javadocs instead of the release pinned javadocs is fine. I believe you are getting the class from JDK17 running on the JVM of an earlier version.
• One related bug is docs linked to with the -doc-external-doc command line option are also missing the module name (if there is any) in the URL.

[Math-ias]

A different but related replication would be to use the -doc-external-doc flag instead of -release. In the sandbox ...

mkdir java; mkdir java/org; mkdir java/org/alice; mkdir java/org/alice/bob;
echo "module org.xavier.zach { exports org.alice.bob; }" > java/module-info.java
echo "package org.alice.bob;" >> java/org/alice/bob/Interface.java
echo "public interface Interface {}" >> java/org/alice/bob/Interface.java
javac java/module-info.java java/org/alice/bob/Interface.java
javadoc -d javadocs -sourcepath java -subpackages org
echo "/** Example: [[org.alice.bob.Interface]] .*/" >> Example.scala
echo "class Example" >> Example.scala
mkdir scaladocs
../build/pack/bin/scaladoc -classpath java -doc-external-doc:'/Users/math-ias/scala/sandbox/java#file:///Users/math-ias/scala/sandbox/javadocs/' -d scaladocs/ Example.scala

The generated scala docs link to ...

% xmllint --html --xpath '//a/@href' scaladocs/Example.html 2>/dev/null | grep "file:///" | sed 's/href="//g; s/"$//g' | sort | uniq
file:///Users/math-ias/scala/sandbox/javadocs/org/alice/bob/Interface.html

Which is missing the java module prefix.

% find javadocs -name "Interface.html"
javadocs/org.xavier.zach/org/alice/bob/Interface.html

[SethTisue]

I suspect linking the latest javadocs instead of the release pinned javadocs is fine. I believe you are getting the class from JDK17 running on the JVM of an earlier version.

If you're running an older JVM, the older JVM is it, that's all you have. I don't understand how you would be "getting the class from JDK17 running on the JVM of an earlier version" or what that even means?

It sounds like you may have an incorrect belief we need to straighten out, but it's also possible I'm not just following your wording/thinking.

Under -release 11, I do not see any good argument for emitting a link to anything but the API docs for 11. Emitting a link to 17 might be better than nothing, but I don't see a case for considering it actually correct.

[Math-ias]

I was mistaken when I first wrote that comment. In the PR we've started linking to javadocs versioned by the release option https://github.com/scala/scala/pull/10881/files#diff-c22532b7be6a4b9fe8f6759b3ac0ba2c9533f92e07e4704be5bb891ee1e79f0dR155.