From d22b74c22fef4151533bf23efcc6b4f59e60d88f Mon Sep 17 00:00:00 2001 From: Eugene Vigdorchik Date: Thu, 11 Oct 2012 12:41:54 +0400 Subject: Scaladoc knows the package structure of the libraries, so don't include them in external documentation setting. --- src/compiler/scala/tools/nsc/doc/Settings.scala | 32 +++++---- .../scala/tools/nsc/doc/model/MemberLookup.scala | 6 +- .../scala/tools/nsc/doc/model/ModelFactory.scala | 27 ++++++-- .../nsc/doc/model/ModelFactoryTypeSupport.scala | 2 +- src/manual/scala/man1/scaladoc.scala | 5 +- test/scaladoc/run/SI-191-deprecated.check | 1 + test/scaladoc/run/SI-191-deprecated.scala | 71 ++++++++++++++++++++ test/scaladoc/run/SI-191.check | 1 + test/scaladoc/run/SI-191.scala | 76 ++++++++++++++++++++++ 9 files changed, 199 insertions(+), 22 deletions(-) create mode 100755 test/scaladoc/run/SI-191-deprecated.check create mode 100755 test/scaladoc/run/SI-191-deprecated.scala create mode 100755 test/scaladoc/run/SI-191.check create mode 100755 test/scaladoc/run/SI-191.scala 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") + } +} -- cgit v1.2.3