Incorrect scaladoc links to JDK apidocs

[durban]

Links to JDK APIs in the generated scaladoc seem to be incorrect. Two examples:

• In the Cats Effect documentation: java.security.SecureRandom links to https://docs.oracle.com/en/java/javase/11/docs/api/java/security/SecureRandom.html (which is a dead link).
• Here: java.util.concurrent.atomic.AtomicReference links to https://docs.oracle.com/en/java/javase/17/docs/api/java/util/concurrent/atomic/AtomicReference.html (which is also a dead link).

In theory this can be an sbt/scaladoc bug, but I see some settings here, which seem related, but somehow they're not applied(?).

[armanbilge]

Hmm, maybe we forgot to prefix it with Compile /? 🤔 https://github.com/typelevel/sbt-typelevel/blob/1f6850a0906ffdb47086a24d268e3f51b9a43408/settings/src/main/scala/org/typelevel/sbt/TypelevelSettingsPlugin.scala#L370

[armanbilge]

No, that seems fine. So now I suspect maybe we are not mapping the right thing 🤔

https://github.com/typelevel/sbt-typelevel/blob/1f6850a0906ffdb47086a24d268e3f51b9a43408/settings/src/main/scala/org/typelevel/sbt/TypelevelSettingsPlugin.scala#L388

FTR that's cargo-culted from here. https://github.com/scala-js/scala-js/blob/e0afd0f096c6b096ce7ad17f46c07142ac80c7ef/project/Build.scala#L442-L446

[armanbilge]

I think we should try refreshing our cargo-cult with exactly whats in Scala.js, for example this part seems interesting.

https://github.com/scala-js/scala-js/blob/e0afd0f096c6b096ce7ad17f46c07142ac80c7ef/project/Build.scala#L428-L430

[armanbilge]

Tried fixing this in 4b8962bdb2921a578e9cb66cf89515bf5ecdf09d but it didn't fix Choam 😕 so either we're still not doing it right, or perhaps sbt is overriding us.

[durban]

Thanks for trying! This whole apiMappings setting is very mysterious to me, so I don't have any ideas...

[durban]

~~Have we seen this setting working anywhere? I see that in the scala-js API it seems to work; I suspect that's because it uses the old (JVM 8) url...~~

• looking at the code, sbt generates -doc-external-doc cmdline options for scaladoc: https://github.com/sbt/sbt/blob/1.9.x/main/src/main/scala/sbt/Opts.scala#L41
• ~~scaladoc however, seems to ignore that option for JDK symbols: https://github.com/scala/scala/blob/2.13.x/src/scaladoc/scala/tools/nsc/doc/model/MemberLookup.scala#L64C1-L64C1~~
• ~~and instead it uses it's own URL, which seems to be incorrect(?): https://github.com/scala/scala/blob/2.13.x/src/scaladoc/scala/tools/nsc/doc/model/MemberLookup.scala#L123~~

Edit: what I wrote above is incorrect, I still don't understand what's happening.

[durban]

There is a strange interaction with the -release option, but it doesn't seem sbt-typelevel specific, so I've opened https://github.com/scala/bug/issues/12820.

[armanbilge]

Aha, I see, thanks for investigating. But this does illustrate our setting is not really doing anything.