diff options
author | Josh Suereth <Joshua.Suereth@gmail.com> | 2012-10-20 18:06:29 -0700 |
---|---|---|
committer | Josh Suereth <Joshua.Suereth@gmail.com> | 2012-10-20 18:06:29 -0700 |
commit | 1899c91b149c6508c1d527fcbdbc9310f627c21f (patch) | |
tree | 340c2542a9909d1021a0569415209958098b605b /src | |
parent | 9dbb0675352a36965c556b678bec2b1ffc3d2e45 (diff) | |
parent | d22b74c22fef4151533bf23efcc6b4f59e60d88f (diff) | |
download | scala-1899c91b149c6508c1d527fcbdbc9310f627c21f.tar.gz scala-1899c91b149c6508c1d527fcbdbc9310f627c21f.tar.bz2 scala-1899c91b149c6508c1d527fcbdbc9310f627c21f.zip |
Merge pull request #1479 from vigdorchik/2.10.x
Scaladoc knows the package structure of the libraries,
Diffstat (limited to 'src')
5 files changed, 50 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 1c783a7d2c..5257db1610 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 } @@ -171,7 +171,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 73b4341e95..496aeb4aa1 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 } // Defaults for member grouping, that may be overridden by the template @@ -1097,12 +1097,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( |