Support Java API doc Scaladoc/Unidoc References

[seldridge]

This enables automatic Scaladoc linking to Java API docs using the same strategy that Scala upstream uses.

Linking to Scala API documentation already works.

Contributor Checklist

• Did you add Scaladoc to every public function/method?
• Did you add at least one test demonstrating the PR?
• Did you delete any extraneous printlns/debugging code?
• Did you specify the type of improvement?
• Did you state the API impact?
• Did you specify the code generation impact?
• Did you request a desired merge strategy?

Type of Improvement

• documentation

API Impact

None.

Backend Code Generation Impact

None.

Desired Merge Strategy

• Squash: The PR will be squashed and merged (choose this if you have no preference.

Reviewer Checklist (only modified by reviewer)

• Did you add the appropriate labels?
• Did you mark the proper milestone (1.2.x, 1.3.0, 1.4.0) ?
• Did you review?
• Did you mark as Please Merge?

[chick]

This looks pretty simple. Can anything go wrong here?

[seldridge]

I have no earthly idea why this isn't building on Travis... 🤷‍♀️ This works locally with a clean clone and a nuked ~/.ivy2.

[ucbjrl]

It looks like the plugin has been compiled for Java 8 and won't work with Java 11 or 13.

[seldridge]

Ugh, thanks Jim. Scala does something different for linking to Java API docs. I can at least add that.

[ucbjrl]

The incompatibility doesn't appear to be fundamental in nature. If you generate a full log, you get:

[error] scala.MatchError: 11 (of class java.lang.String)
[error] 	at com.thoughtworks.sbtApiMappings.BootstrapApiMappings$.$anonfun$globalSettings$1(BootstrapApiMappings.scala:28)
[error] 	at sbt.internal.util.Init$Value.$anonfun$apply$3(Settings.scala:823)

and the code at that location is:

  private[sbtApiMappings] def defaultBootstrapJavadocUrl = {
    val javaVersion = sys.props("java.specification.version") match {
->      case VersionNumber(Seq(1, javaVersion, _*), _, _) => javaVersion // 1.6-1.8
        case VersionNumber(Seq(javaVersion, _*),    _, _) => javaVersion // 9+
        case _ =>                                            8
    }
    if (javaVersion >= 11) {
      url(s"https://docs.oracle.com/en/java/javase/${javaVersion}/docs/api/index.html")
    } else {
      url(s"https://docs.oracle.com/javase/${javaVersion}/docs/api/index.html")
    }
  }

java.specification.version for post Java 9 has changed. See https://stackoverflow.com/questions/5103121/how-to-find-the-jvm-version-from-a-program

[seldridge]

I switched this to not use the sbt-api-mappings plugin to avoid the issue that @ucbjrl found (also that plugin is sparsely updated making me nervous). Instead, this uses the same strategy that Scala uses to link against Java API documentation. The small example included works for unidoc.

[chick]

lgtm