SI-3695 SI-4224 SI-4497 SI-5079 scaladoc links

Adds the ability to link to members, classes and objects in scaladoc.
The links can now be either qualified names or relative names, they
both work. See the test/scaladoc/resources/links.scala for a usage
example. Also introduced -no-link-warnings scaladoc flag, in case the
build output gets swamped with link warnings.

1 files changed, 185 insertions, 0 deletions

diff --git a/src/compiler/scala/tools/nsc/doc/model/MemberLookup.scala b/src/compiler/scala/tools/nsc/doc/model/MemberLookup.scala
new file mode 100644
index 0000000000..7b131c13ef
--- /dev/null
+++ b/src/compiler/scala/tools/nsc/doc/model/MemberLookup.scala
@@ -0,0 +1,185 @@
+package scala.tools.nsc
+package doc
+package model
+
+import comment._
+
+import scala.reflect.internal.util.FakePos //Position
+
+/** This trait extracts all required information for documentation from compilation units */
+trait MemberLookup {
+  thisFactory: ModelFactory =>
+
+  import global._
+
+  def memberLookup(pos: Position, query: String, inTplOpt: Option[DocTemplateImpl]): LinkTo = {
+    assert(modelFinished)
+
+    var members = breakMembers(query)
+    //println(query + " => " + members)
+
+    // (1) Lookup in the root package, as most of the links are qualified
+    var linkTo: List[LinkTo] = lookupInRootPackage(pos, members)
+
+    // (2) Recursively go into each
+    if (inTplOpt.isDefined) {
+      var currentTpl = inTplOpt.get
+      while (currentTpl != null && !currentTpl.isRootPackage && (linkTo.isEmpty)) {
+        linkTo = lookupInTemplate(pos, members, currentTpl)
+        currentTpl = currentTpl.inTemplate
+      }
+      if (currentTpl == null) println("\n\n\n\n\nnull found in:" + inTplOpt + "\n\n\n\n\n\n\n\n")
+    }
+
+    // (3) Look at external links
+    if (linkTo.isEmpty) {
+      // TODO: IF THIS IS THE ROOT PACKAGE, LOOK AT EXTERNAL LINKS
+    }
+
+    // (4) if we still haven't found anything, create a tooltip, if we found too many, report
+    if (linkTo.isEmpty){
+      if (!settings.docNoLinkWarnings.value)
+        reporter.warning(pos, "Could not find any member to link for \"" + query + "\".")
+      Tooltip(query)
+    } else {
+      if (linkTo.length > 1) {
+
+        val chosen =
+          if (linkTo.exists(_.isInstanceOf[LinkToMember]))
+            linkTo.collect({case lm: LinkToMember => lm}).min(Ordering[MemberEntity].on[LinkToMember](_.mbr))
+          else
+            linkTo.head
+
+        def linkToString(link: LinkTo) = {
+          val description =
+            link match {
+              case lm@LinkToMember(mbr, inTpl) => " * " + mbr.kind + " \"" + mbr.signature + "\" in " + inTpl.kind + " " + inTpl.qualifiedName
+              case lt@LinkToTpl(tpl) => " * " + tpl.kind + " \"" + tpl.qualifiedName + "\""
+              case other => " * " + other.toString
+            }
+          val chosenInfo =
+            if (link == chosen)
+              " [chosen]"
+            else
+              ""
+          description + chosenInfo + "\n"
+        }
+        if (!settings.docNoLinkWarnings.value)
+          reporter.warning(pos,
+            "The link target \"" + query + "\" is ambiguous. Several (possibly overloaded) members fit the target:\n" +
+            linkTo.map(link => linkToString(link)).mkString +
+            (if (MemberLookup.showExplanation)
+              "\n\n" +
+              "Quick crash course on using Scaladoc links\n" +
+              "==========================================\n" +
+              "Disambiguating terms and types: Prefix terms with '$' and types with '!' in case both names are in use:\n" +
+              " - [[scala.collection.immutable.List!.apply class List's apply method]] and\n" +
+              " - [[scala.collection.immutable.List$.apply object List's apply method]]\n" +
+              "Disambiguating overloaded members: If a term is overloaded, you can indicate the first part of its signature followed by *:\n" +
+              " - [[[scala.collection.immutable.List$.fill[A](Int)(⇒A):List[A]* Fill with a single parameter]]]\n" +
+              " - [[[scala.collection.immutable.List$.fill[A](Int,Int)(⇒A):List[List[A]]* Fill with a two parameters]]]\n" +
+              "Notes: \n" +
+              " - you can use any number of matching square brackets to avoid interference with the signature\n" +
+              " - you can use \\. to escape dots in prefixes (don't forget to use * at the end to match the signature!)\n" +
+              " - you can use \\# to escape hashes, otherwise they will be considered as delimiters, like dots.\n"
+            else "")
+        )
+        chosen
+      } else
+        linkTo.head
+    }
+  }
+
+  private abstract class SearchStrategy
+  private object BothTypeAndTerm extends SearchStrategy
+  private object OnlyType extends SearchStrategy
+  private object OnlyTerm extends SearchStrategy
+
+  private def lookupInRootPackage(pos: Position, members: List[String]) = lookupInTemplate(pos, members, makeRootPackage)
+
+  private def lookupInTemplate(pos: Position, members: List[String], inTpl: DocTemplateImpl): List[LinkTo] = {
+    // Maintaining compatibility with previous links is a bit tricky here:
+    // we have a preference for term names for all terms except for the last, where we prefer a class:
+    // How to do this:
+    //  - at each step we do a DFS search with the prefered strategy
+    //  - if the search doesn't return any members, we backtrack on the last decision
+    //     * we look for terms with the last member's name
+    //     * we look for types with the same name, all the way up
+    val result = members match {
+      case Nil =>
+        Nil
+      case mbrName::Nil =>
+        var members = lookupInTemplate(pos, mbrName, inTpl, OnlyType)
+        if (members.isEmpty)
+          members = lookupInTemplate(pos, mbrName, inTpl, OnlyTerm)
+
+        members.map(_ match {
+          case tpl: DocTemplateEntity => LinkToTpl(tpl)
+          case mbr => LinkToMember(mbr, inTpl)
+        })
+
+      case tplName::rest =>
+
+        def completeSearch(mbrs: List[MemberImpl]) =
+          mbrs.collect({case d:DocTemplateImpl => d}).flatMap(tpl => lookupInTemplate(pos, rest, tpl))
+
+        var members = completeSearch(lookupInTemplate(pos, tplName, inTpl, OnlyTerm))
+        if (members.isEmpty)
+          members = completeSearch(lookupInTemplate(pos, tplName, inTpl, OnlyType))
+
+        members
+    }
+    //println("lookupInTemplate(" + members + ", " + inTpl + ") => " + result)
+    result
+  }
+
+  private def lookupInTemplate(pos: Position, member: String, inTpl: DocTemplateImpl, strategy: SearchStrategy): List[MemberImpl] = {
+    val name = member.stripSuffix("$").stripSuffix("!").stripSuffix("*")
+    val result = if (member.endsWith("$"))
+      inTpl.members.filter(mbr => (mbr.name == name) && (mbr.isTerm))
+    else if (member.endsWith("!"))
+      inTpl.members.filter(mbr => (mbr.name == name) && (mbr.isType))
+    else if (member.endsWith("*"))
+      inTpl.members.filter(mbr => (mbr.signature.startsWith(name)))
+    else {
+      if (strategy == BothTypeAndTerm)
+        inTpl.members.filter(_.name == name)
+      else if (strategy == OnlyType)
+        inTpl.members.filter(mbr => (mbr.name == name) && (mbr.isType))
+      else if (strategy == OnlyTerm)
+        inTpl.members.filter(mbr => (mbr.name == name) && (mbr.isTerm))
+      else
+        Nil
+    }
+
+    //println("lookupInTemplate(" + member + ", " + inTpl + ") => " + result)
+    result
+  }
+
+  private def breakMembers(query: String): List[String] = {
+    // Okay, how does this work? Well: you split on . but you don't want to split on \. => thus the ugly regex
+    // query.split((?<=[^\\\\])\\.).map(_.replaceAll("\\."))
+    // The same code, just faster:
+    var members = List[String]()
+    var index = 0
+    var last_index = 0
+    val length = query.length
+    while (index < length) {
+      if ((query.charAt(index) == '.' || query.charAt(index) == '#') &&
+          ((index == 0) || (query.charAt(index-1) != '\\'))) {
+
+        members ::= query.substring(last_index, index).replaceAll("\\\\([#\\.])", "$1")
+        last_index = index + 1
+      }
+      index += 1
+    }
+    if (last_index < length)
+      members ::= query.substring(last_index, length).replaceAll("\\\\\\.", ".")
+    members.reverse
+  }
+}
+
+object MemberLookup {
+  private[this] var _showExplanation = true
+  def showExplanation: Boolean = if (_showExplanation) { _showExplanation = false; true } else false
+}
\ No newline at end of file