summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--src/compiler/scala/tools/nsc/doc/Settings.scala32
-rw-r--r--src/compiler/scala/tools/nsc/doc/model/MemberLookup.scala6
-rw-r--r--src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala27
-rw-r--r--src/compiler/scala/tools/nsc/doc/model/ModelFactoryTypeSupport.scala2
-rw-r--r--src/manual/scala/man1/scaladoc.scala5
-rwxr-xr-xtest/scaladoc/run/SI-191-deprecated.check1
-rwxr-xr-xtest/scaladoc/run/SI-191-deprecated.scala71
-rwxr-xr-xtest/scaladoc/run/SI-191.check1
-rwxr-xr-xtest/scaladoc/run/SI-191.scala76
9 files changed, 199 insertions, 22 deletions
diff --git a/src/compiler/scala/tools/nsc/doc/Settings.scala b/src/compiler/scala/tools/nsc/doc/Settings.scala
index 64a376b96e..94ebbf2c12 100644
--- a/src/compiler/scala/tools/nsc/doc/Settings.scala
+++ b/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. :)
diff --git a/src/compiler/scala/tools/nsc/doc/model/MemberLookup.scala b/src/compiler/scala/tools/nsc/doc/model/MemberLookup.scala
index 7ab73cceff..21fd086231 100644
--- a/src/compiler/scala/tools/nsc/doc/model/MemberLookup.scala
+++ b/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)))
diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala
index 07526a5608..44e10d1c75 100644
--- a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala
+++ b/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
diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactoryTypeSupport.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactoryTypeSupport.scala
index c67a398bb7..c435930c7c 100644
--- a/src/compiler/scala/tools/nsc/doc/model/ModelFactoryTypeSupport.scala
+++ b/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)
)
diff --git a/src/manual/scala/man1/scaladoc.scala b/src/manual/scala/man1/scaladoc.scala
index ac2a16ccb3..0f2b1cde8a 100644
--- a/src/manual/scala/man1/scaladoc.scala
+++ b/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(
diff --git a/test/scaladoc/run/SI-191-deprecated.check b/test/scaladoc/run/SI-191-deprecated.check
new file mode 100755
index 0000000000..3925a0d464
--- /dev/null
+++ b/test/scaladoc/run/SI-191-deprecated.check
@@ -0,0 +1 @@
+Done. \ No newline at end of file
diff --git a/test/scaladoc/run/SI-191-deprecated.scala b/test/scaladoc/run/SI-191-deprecated.scala
new file mode 100755
index 0000000000..746aa9c598
--- /dev/null
+++ b/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")
+ }
+}
diff --git a/test/scaladoc/run/SI-191.check b/test/scaladoc/run/SI-191.check
new file mode 100755
index 0000000000..3925a0d464
--- /dev/null
+++ b/test/scaladoc/run/SI-191.check
@@ -0,0 +1 @@
+Done. \ No newline at end of file
diff --git a/test/scaladoc/run/SI-191.scala b/test/scaladoc/run/SI-191.scala
new file mode 100755
index 0000000000..0fb28145c3
--- /dev/null
+++ b/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")
+ }
+}
generated by cgit v1.2.3 (git 2.39.1) at 2024-05-31 18:31:27 +0000