Support Java API doc Scaladoc/Unidoc References (#1420)

* Link to Java API Documentation

This adds a build.sbt apiMappings to allow for Scaladoc/Unidoc linking
to Java API documentation. This uses the exact strategy that Scala
upstream uses for linking.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* Add example of Java and Scala API docs linking

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

build.sbt

@@ -136,6 +136,18 @@ lazy val publishSettings = Seq(
 lazy val docSettings = Seq(
   doc in Compile := (doc in ScalaUnidoc).value,
   autoAPIMappings := true,
+  apiMappings ++= {
+    Option(System.getProperty("sun.boot.class.path")).flatMap { classPath =>
+      classPath.split(java.io.File.pathSeparator).find(_.endsWith(java.io.File.separator + "rt.jar"))
+    }.map { jarPath =>
+      Map(
+        file(jarPath) -> url("https://docs.oracle.com/javase/8/docs/api")
+      )
+    }.getOrElse {
+      streams.value.log.warn("Failed to add bootstrap class path of Java to apiMappings")
+      Map.empty[File,URL]
+    }
+  },
   scalacOptions in Compile in doc ++= Seq(
     "-diagrams",
     "-diagrams-max-classes", "25",

src/main/scala/firrtl/options/Exceptions.scala

@@ -11,6 +11,8 @@ class PhaseException(val message: String, cause: Throwable = null) extends Runti
 /** Indicate an error related to a bad [[firrtl.annotations.Annotation Annotation]] or it's command line option
   * equivalent. This exception is always caught and converted to an error message by a [[Stage]]. Do not use this for
   * communicating generic exception information.
+  * @param message exception message [[scala.Predef.String String]]
+  * @param cause the reason for this exception (a Java [[java.lang.Throwable Throwable]])
   */
 class OptionsException(val message: String, cause: Throwable = null) extends IllegalArgumentException(message, cause)