Scaladoc knows the package structure of the libraries,

so don't include them in external documentation setting.

Author: vigdorchik

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

@@ -7,6 +7,7 @@ package scala.tools.nsc
 package doc
 
 import java.io.File
+import java.net.URI
 import java.lang.System
 import scala.language.postfixOps
 
@@ -71,6 +72,12 @@ class Settings(error: String => Unit, val printMsg: String => Unit = println(_))
     ""
   )
 
+  val docExternalUris = MultiStringSetting (
+    "-doc-external-uris",
+    "external-doc",
+    "comma-separated list of file://classpath_entry_path#doc_URL URIs for external dependencies"
+  )
+
   val useStupidTypes = BooleanSetting (
     "-Yuse-stupid-types",
     "Print the types of inherited members as seen from their original definition context. Hint: you don't want to do that!"
@@ -197,7 +204,7 @@ class Settings(error: String => Unit, val printMsg: String => Unit = println(_))
   val docExternalUrls = MultiStringSetting (
     "-external-urls",
     "externalUrl(s)",
-    "comma-separated list of package_names=doc_URL for external dependencies, where package names are ':'-separated"
+    "(deprecated) comma-separated list of package_names=doc_URL for external dependencies, where package names are ':'-separated"
   )
 
   val docGroups = BooleanSetting (
@@ -244,22 +251,25 @@ class Settings(error: String => Unit, val printMsg: String => Unit = println(_))
     }
   }
 
-  // TODO: Enable scaladoc to scoop up the package list from another scaladoc site, just as javadoc does
-  //   -external-urls 'http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/library'
-  // should trigger scaldoc to fetch the package-list file. The steps necessary:
-  // 1 - list all packages generated in scaladoc in the package-list file, exactly as javadoc:
-  //     see http://docs.oracle.com/javase/6/docs/api/package-list for http://docs.oracle.com/javase/6/docs/api
-  // 2 - download the file and add the packages to the list
-  lazy val extUrlMapping: Map[String, String] = (Map.empty[String, String] /: docExternalUrls.value) {
+  def appendIndex(url: String): String = {
+    val index = "/index.html"
+    if (url.endsWith(index)) url else url + index
+  }
+
+  // Deprecated together with 'docExternalUrls' option.
+  lazy val extUrlPackageMapping: Map[String, String] = (Map.empty[String, String] /: docExternalUrls.value) {
     case (map, binding) =>
       val idx = binding indexOf "="
       val pkgs = binding substring (0, idx) split ":"
-      var url = binding substring (idx + 1)
-      val index = "/index.html"
-      url = if (url.endsWith(index)) url else url + index
+      val url = appendIndex(binding substring (idx + 1))
       map ++ (pkgs map (_ -> url))
   }
 
+  lazy val extUrlMapping: Map[String, String] = docExternalUris.value map { s =>
+    val uri = new URI(s)
+    uri.getSchemeSpecificPart -> appendIndex(uri.getFragment)
+  } toMap
+
   /**
    *  This is the hardcoded area of Scaladoc. This is where "undesirable" stuff gets eliminated. I know it's not pretty,
    *  but ultimately scaladoc has to be useful. :)

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

@@ -48,9 +48,9 @@ trait MemberLookup {
           }
 
           if (sym.isClass || sym.isModule || sym.isTrait || sym.isPackage)
-            findExternalLink(linkName(sym))
+            findExternalLink(sym, linkName(sym))
           else if (owner.isClass || owner.isModule || owner.isTrait || owner.isPackage)
-            findExternalLink(linkName(owner) + "@" + externalSignature(sym))
+            findExternalLink(sym, linkName(owner) + "@" + externalSignature(sym))
           else
             None
         }
@@ -173,7 +173,7 @@ trait MemberLookup {
     // and removing NoType classes
     def cleanupBogusClasses(syms: List[Symbol]) = { syms.filter(_.info != NoType) }
 
-    def syms(name: Name) = container.info.nonPrivateMember(name).alternatives
+    def syms(name: Name) = container.info.nonPrivateMember(name.encodedName).alternatives
     def termSyms = cleanupBogusClasses(syms(newTermName(name)))
     def typeSyms = cleanupBogusClasses(syms(newTypeName(name)))
 

src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala

@@ -28,7 +28,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) {
                with MemberLookup =>
 
   import global._
-  import definitions.{ ObjectClass, NothingClass, AnyClass, AnyValClass, AnyRefClass }
+  import definitions.{ ObjectClass, NothingClass, AnyClass, AnyValClass, AnyRefClass, ListClass }
   import rootMirror.{ RootPackage, RootClass, EmptyPackage }
 
   def templatesCount = docTemplatesCache.count(_._2.isDocTemplate) - droppedPackages.size
@@ -1084,12 +1084,27 @@ class ModelFactory(val global: Global, val settings: doc.Settings) {
     { val rawComment = global.expandedDocComment(bSym, inTpl.sym)
       rawComment.contains("@template") || rawComment.contains("@documentable") }
 
-  def findExternalLink(name: String): Option[LinkTo] =
-    settings.extUrlMapping find {
-      case (pkg, _) => name startsWith pkg
-    } map {
-      case (_, url) => LinkToExternal(name, url + "#" + name)
+  def findExternalLink(sym: Symbol, name: String): Option[LinkTo] = {
+    val sym1 =
+      if (sym == AnyClass || sym == AnyRefClass || sym == AnyValClass || sym == NothingClass) ListClass
+      else if (sym.isPackage) 
+        /* Get package object which has associatedFile ne null */
+        sym.info.member(newTermName("package"))
+      else sym
+    Option(sym1.associatedFile) flatMap (_.underlyingSource) flatMap { src =>
+      val path = src.path
+      settings.extUrlMapping get path map { url =>
+        LinkToExternal(name, url + "#" + name)
+      }
+    } orElse {
+      // Deprecated option.
+      settings.extUrlPackageMapping find {
+        case (pkg, _) => name startsWith pkg
+      } map {
+        case (_, url) => LinkToExternal(name, url + "#" + name)
+      }
     }
+  }
 
   def externalSignature(sym: Symbol) = {
     sym.info // force it, otherwise we see lazy types

src/compiler/scala/tools/nsc/doc/model/ModelFactoryTypeSupport.scala

@@ -104,7 +104,7 @@ trait ModelFactoryTypeSupport {
                     if (!bSym.owner.isPackage)
                       Tooltip(name)
                     else
-                      findExternalLink(name).getOrElse (
+                      findExternalLink(bSym, name).getOrElse (
                         // (3) if we couldn't find neither the owner nor external URL to link to, show a tooltip with the qualified name
                         Tooltip(name)
                       )

src/manual/scala/man1/scaladoc.scala

@@ -75,7 +75,10 @@ object scaladoc extends Command {
           "Define the overall version number of the documentation, typically the version of the library being documented."),
         Definition(
           CmdOption("doc-source-url", Argument("url")),
-          "Define a URL to be concatenated with source locations for link to source files."))),
+          "Define a URL to be concatenated with source locations for link to source files."),
+        Definition(
+          CmdOption("doc-external-uris", Argument("external-doc")),
+          "Define comma-separated list of file://classpath_entry_path#doc_URL URIs for linking to external dependencies."))),
 
     Section("Compiler Options",
       DefinitionList(

test/scaladoc/run/SI-191-deprecated.check

@@ -0,0 +1 @@
+Done.

test/scaladoc/run/SI-191-deprecated.scala

@@ -0,0 +1,71 @@
+import scala.tools.nsc.doc.model._
+import scala.tools.nsc.doc.model.comment._
+import scala.tools.partest.ScaladocModelTest
+import java.net.{URI, URL}
+import java.io.File
+
+object Test extends ScaladocModelTest {
+
+  override def code =
+    """
+        /** See:
+         *  - [[scala.collection.Map]] Simple linking
+         *  - [[scala.collection.immutable.::]] Linking with symbolic name
+         *  - [[scala.Int]].toLong Linking to a class
+         *  - [[scala.Predef]] Linking to an object
+         *  - [[scala.Int.toLong]] Linking to a method
+         *  - [[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
+         *
+         *  Don't look at:
+         *  - [[scala.NoLink]] Not linking :)
+         */
+        object Test {
+          def foo(param: Any) {}
+          def barr(l: scala.collection.immutable.List[Any]) {}
+          def bar(l: List[String]) {}   // TODO: Should be able to link to type aliases
+          def baz(d: java.util.Date) {} // Should not be resolved
+        }
+    """
+
+  def scalaURL = "http://bog.us"
+
+  override def scaladocSettings =  "-no-link-warnings -external-urls scala=" + scalaURL
+
+  def testModel(rootPackage: Package) {
+    import access._
+    val test = rootPackage._object("Test")
+
+    def check(memberDef: Def, expected: Int) {
+      val externals = memberDef.valueParams(0)(0).resultType.refEntity collect {
+        case (_, (LinkToExternal(name, url), _)) => assert(url.contains(scalaURL)); name
+      }
+      assert(externals.size == expected)
+    }
+
+    check(test._method("foo"), 1)
+    check(test._method("bar"), 0)
+    check(test._method("barr"), 2)
+    check(test._method("baz"), 0)
+
+    val expectedUrls = collection.mutable.Set[String](
+                         "scala.collection.Map",
+                         "scala.collection.immutable.::",
+                         "scala.Int",
+                         "scala.Predef$",
+                         "scala.Int@toLong:Long",
+                         "scala.package",
+                         "scala.package@AbstractMethodError=AbstractMethodError",
+                         "scala.Predef$@String=String"
+                       ).map(scalaURL + "/index.html#" + _)
+
+    def isExpectedExternalLink(l: EntityLink) = l.link match {
+      case LinkToExternal(name, url) => assert(expectedUrls contains url, url); true
+      case _ => false
+    }
+
+    assert(countLinks(test.comment.get, isExpectedExternalLink) == 8,
+           countLinks(test.comment.get, isExpectedExternalLink) + " == 8")
+  }
+}

test/scaladoc/run/SI-191.check

@@ -0,0 +1 @@
+Done.

test/scaladoc/run/SI-191.scala

@@ -0,0 +1,76 @@
+import scala.tools.nsc.doc.model._
+import scala.tools.nsc.doc.model.comment._
+import scala.tools.partest.ScaladocModelTest
+import java.net.{URI, URL}
+import java.io.File
+
+object Test extends ScaladocModelTest {
+
+  override def code =
+    """
+        /** See:
+         *  - [[scala.collection.Map]] Simple linking
+         *  - [[scala.collection.immutable.::]] Linking with symbolic name
+         *  - [[scala.Int]].toLong Linking to a class
+         *  - [[scala.Predef]] Linking to an object
+         *  - [[scala.Int.toLong]] Linking to a method
+         *  - [[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
+         *
+         *  Don't look at:
+         *  - [[scala.NoLink]] Not linking :)
+         */
+        object Test {
+          def foo(param: Any) {}
+          def barr(l: scala.collection.immutable.List[Any]) {}
+          def bar(l: List[String]) {}   // TODO: Should be able to link to type aliases
+          def baz(d: java.util.Date) {} // Should not be resolved
+        }
+    """
+
+  def scalaURL = "http://bog.us"
+
+  override def scaladocSettings = {
+    val scalaLibUri = getClass.getClassLoader.getResource("scala/Function1.class").toURI.getSchemeSpecificPart.split("!")(0)
+    val scalaLib = new File(new URL(scalaLibUri).getPath).getPath
+    val extArg = new URI("file", scalaLib, scalaURL).toString
+    "-no-link-warnings -doc-external-uris " + extArg
+  }
+
+  def testModel(rootPackage: Package) {
+    import access._
+    val test = rootPackage._object("Test")
+
+    def check(memberDef: Def, expected: Int) {
+      val externals = memberDef.valueParams(0)(0).resultType.refEntity collect {
+        case (_, (LinkToExternal(name, url), _)) => assert(url.contains(scalaURL)); name
+      }
+      assert(externals.size == expected)
+    }
+
+    check(test._method("foo"), 1)
+    check(test._method("bar"), 0)
+    check(test._method("barr"), 2)
+    check(test._method("baz"), 0)
+
+    val expectedUrls = collection.mutable.Set[String](
+                         "scala.collection.Map",
+                         "scala.collection.immutable.::",
+                         "scala.Int",
+                         "scala.Predef$",
+                         "scala.Int@toLong:Long",
+                         "scala.package",
+                         "scala.package@AbstractMethodError=AbstractMethodError",
+                         "scala.Predef$@String=String"
+                       ).map(scalaURL + "/index.html#" + _)
+
+    def isExpectedExternalLink(l: EntityLink) = l.link match {
+      case LinkToExternal(name, url) => assert(expectedUrls contains url, url); true
+      case _ => false
+    }
+
+    assert(countLinks(test.comment.get, isExpectedExternalLink) == 8,
+           countLinks(test.comment.get, isExpectedExternalLink) + " == 8")
+  }
+}