Fix broken Scaladoc external Java references

Fixes scala/bug#11839

Author: steven-barnes

project/ScalaOptionParser.scala

@@ -124,7 +124,7 @@ object ScalaOptionParser {
   private def scalaDocBooleanSettingNames = List("-implicits", "-implicits-debug", "-implicits-show-all", "-implicits-sound-shadowing", "-implicits-hide", "-author", "-diagrams", "-diagrams-debug", "-raw-output", "-no-prefixes", "-no-link-warnings", "-expand-all-types", "-groups")
   private def scalaDocIntSettingNames = List("-diagrams-max-classes", "-diagrams-max-implicits", "-diagrams-dot-timeout", "-diagrams-dot-restart")
   private def scalaDocChoiceSettingNames = Map("-doc-format" -> List("html"))
-  private def scaladocStringSettingNames = List("-doc-title", "-doc-version", "-doc-footer", "-doc-no-compile", "-doc-source-url", "-doc-generator", "-skip-packages")
+  private def scaladocStringSettingNames = List("-doc-title", "-doc-version", "-doc-footer", "-doc-no-compile", "-doc-source-url", "-doc-generator", "-skip-packages", "jdk-api-doc-base")
   private def scaladocPathSettingNames = List("-doc-root-content", "-diagrams-dot-path")
   private def scaladocMultiStringSettingNames = List("-doc-external-doc")
 

src/manual/scala/man1/scaladoc.scala

@@ -77,7 +77,11 @@ object scaladoc extends Command {
           "Define a URL to be concatenated with source locations for link to source files."),
         Definition(
           CmdOption("doc-external-doc", Argument("external-doc")),
-          "Define a comma-separated list of classpath_entry_path#doc_URL pairs describing external dependencies."))),
+          "Define a comma-separated list of classpath_entry_path#doc_URL pairs describing external dependencies."),
+        Definition(
+          CmdOption("jdk-api-doc-base", Argument("url")),
+          "Define a URL to be concatenated with source locations for link to Java API."))
+    ),
 
     Section("Compiler Options",
       DefinitionList(

src/reflect/scala/reflect/io/AbstractFile.scala

@@ -18,6 +18,7 @@ import java.io.{BufferedOutputStream, ByteArrayOutputStream, IOException, InputS
 import java.io.{File => JFile}
 import java.net.URL
 import java.nio.ByteBuffer
+import java.nio.file.Paths
 
 import scala.collection.AbstractIterable
 
@@ -265,6 +266,15 @@ abstract class AbstractFile extends AbstractIterable[AbstractFile] {
     fileOrSubdirectoryNamed(name, isDir = true)
   }
 
+  /**
+   * Check if this file is a child of the given directory string. Can only be used
+   * on directories that actually exist in the file system.
+   */
+  def isChildOf(dir: String): Boolean = {
+    val parent = Paths.get(dir).toAbsolutePath().toString
+    canonicalPath.startsWith(parent)
+  }
+
   protected def unsupported(): Nothing = unsupported(null)
   protected def unsupported(msg: String): Nothing = throw new UnsupportedOperationException(msg)
 

src/reflect/scala/reflect/io/PlainFile.scala

@@ -151,7 +151,7 @@ final class PlainNioFile(val nioPath: java.nio.file.Path) extends AbstractFile {
         if (nioPath.getNameCount > 2 && nioPath.startsWith("/modules")) {
           // TODO limit this to OpenJDK based JVMs?
           val moduleName = nioPath.getName(1)
-          Some(new PlainNioFile(Paths.get("/modules", moduleName.toString + ".jmod")))
+          Some(new PlainNioFile(Paths.get(System.getProperty("java.home"), "jmods", moduleName.toString + ".jmod")))
         } else None
       case _ => None
     }

src/scaladoc/scala/tools/nsc/doc/Settings.scala

@@ -85,6 +85,13 @@ class Settings(error: String => Unit, val printMsg: String => Unit = println(_))
     "comma-separated list of classpath_entry_path#doc_URL pairs describing external dependencies."
   )
 
+  val jdkApiDocBase = StringSetting (
+    "-jdk-api-doc-base",
+    "url",
+    "URL used to link Java API references.",
+    ""
+  )
+
   val docgenerator = StringSetting (
     "-doc-generator",
     "class-name",

src/scaladoc/scala/tools/nsc/doc/model/MemberLookup.scala

@@ -57,28 +57,74 @@ trait MemberLookup extends base.MemberLookupBase {
         /* Get package object which has associatedFile ne null */
         sym.info.member(newTermName("package"))
       else sym
-    def classpathEntryFor(s: Symbol): Option[String] = {
-      Option(s.associatedFile).flatMap(_.underlyingSource).map { src =>
-        val path = src.canonicalPath
-        if(path.endsWith(".class")) { // Individual class file -> Classpath entry is root dir
-          val nesting = s.ownerChain.count(_.hasPackageFlag)
-          if(nesting > 0) {
-            val p = 0.until(nesting).foldLeft(src) {
-              case (null, _) => null
-              case (f, _) => f.container
-            }
-            if(p eq null) path else p.canonicalPath
-          } else path
-        } else path // JAR file (and fallback option)
-      }
-    }
     classpathEntryFor(sym1) flatMap { path =>
-      settings.extUrlMapping get path map { url => {
-         LinkToExternalTpl(name, url, makeTemplate(sym))
+      if (isJDK(sym1)) {
+        Some(LinkToExternalTpl(name, jdkUrl(path), makeTemplate(sym)))
+      }
+      else {
+        settings.extUrlMapping get path map { url =>
+          LinkToExternalTpl(name, url, makeTemplate(sym))
         }
       }
     }
   }
 
+  private def classpathEntryFor(s: Symbol): Option[String] = {
+    Option(s.associatedFile).flatMap(_.underlyingSource).map { src =>
+      val path = src.canonicalPath
+      if(path.endsWith(".class")) { // Individual class file -> Classpath entry is root dir
+        val nesting = s.ownerChain.count(_.hasPackageFlag)
+        if(nesting > 0) {
+          val p = 0.until(nesting).foldLeft(src) {
+            case (null, _) => null
+            case (f, _) => f.container
+          }
+          if(p eq null) path else p.canonicalPath
+        } else path
+      } else path // JAR file (and fallback option)
+    }
+  }
+
+  private def isJDK(sym: Symbol) =
+    sym.associatedFile.underlyingSource.map(_.isChildOf(sys.props("java.home"))).getOrElse(false)
+
+  def jdkUrl(path: String): String = {
+    if (path.endsWith(".jmod")) {
+      val tokens = path.split("/")
+      val module = tokens.last.stripSuffix(".jmod")
+      s"$jdkUrl/$module"
+    }
+    else {
+      jdkUrl
+    }
+  }
+
+  def jdkUrl: String = {
+    if (settings.jdkApiDocBase.isDefault)
+      defaultJdkUrl
+    else
+      settings.jdkApiDocBase.value
+  }
+
+  lazy val defaultJdkUrl = {
+    if (javaVersion < 11) {
+      s"https://docs.oracle.com/javase/$javaVersion/docs/api"
+    }
+    else {
+      s"https://docs.oracle.com/en/java/javase/$javaVersion/docs/api"
+    }
+  }
+
+  lazy val javaVersion: Int = {
+    var version = System.getProperty("java.version")
+    (if (version.startsWith("1.")) {
+      version.substring(2, 3)
+    }
+    else {
+      val dot = version.indexOf(".")
+      version.substring(0, dot)
+    }).toInt
+  }
+
   override def warnNoLink = !settings.docNoLinkWarnings.value
 }

test/scaladoc/run/t191.scala

@@ -19,6 +19,7 @@ object Test extends ScaladocModelTest {
          *  - [[scala]] Linking to a package
          *  - [[scala.AbstractMethodError]] Linking to a member in the package object
          *  - [[scala.Predef.String]] Linking to a member in an object
+         *  - [[java.lang.Throwable]] Linking to a class in the JDK
          *
          *  Don't look at:
          *  - [[scala.NoLink]] Not linking :)
@@ -32,6 +33,7 @@ object Test extends ScaladocModelTest {
     """
 
   def scalaURL = "http://bog.us"
+  val jdkUrl = "http://java.us"
 
   override def scaladocSettings = {
     val samplePath = getClass.getClassLoader.getResource("scala/Function1.class").getPath
@@ -41,7 +43,7 @@ object Test extends ScaladocModelTest {
     } else { // individual class files on disk
       samplePath.replace('\\', '/').dropRight("scala/Function1.class".length)
     }
-    s"-no-link-warnings -doc-external-doc $scalaLibPath#$scalaURL"
+    s"-no-link-warnings -doc-external-doc $scalaLibPath#$scalaURL jdk-api-doc-base $jdkUrl"
   }
 
   def testModel(rootPackage: Package): Unit = {
@@ -72,7 +74,7 @@ object Test extends ScaladocModelTest {
                       ).map( _.split("#").toSeq ).map({
                         case Seq(one)      => scalaURL + "/" + one + ".html"
                         case Seq(one, two) => scalaURL + "/" + one + ".html#" + two
-                      })
+                      }) ++ Set(s"$jdkUrl/java/lang.Throwable")
 
     def isExpectedExternalLink(l: EntityLink) = l.link match {
       case LinkToExternalTpl(name, baseUrlString, tpl: TemplateEntity) =>