Merge pull request #2156 from vigdorchik/hierarchy

SI-7109 SI-7153 Generalize the API to get docComments: allow to force do...

6 files changed, 106 insertions, 84 deletions

diff --git a/test/files/presentation/doc.check b/test/files/presentation/doc.check
index e33756773d..5a3ff13151 100644
--- a/test/files/presentation/doc.check
+++ b/test/files/presentation/doc.check
@@ -1,49 +1 @@
-reload: Test.scala
-body:Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(This is a test comment), Text(.)))), Text(
-))))))
-@example:Body(List(Paragraph(Chain(List(Summary(Monospace(Text("abb".permutations = Iterator(abb, bab, bba)))))))))
-@version:
-@since:
-@todo:
-@note:
-@see:
-body:Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(This is a test comment), Text(.)))), Text(
-))))))
-@example:Body(List(Paragraph(Chain(List(Summary(Monospace(Text("abb".permutations = Iterator(abb, bab, bba)))))))))
-@version:Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(1), Text(.)))), Text(0, 09/07/2012))))))
-@since:
-@todo:
-@note:
-@see:
-body:Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(This is a test comment), Text(.)))), Text(
-))))))
-@example:Body(List(Paragraph(Chain(List(Summary(Monospace(Text("abb".permutations = Iterator(abb, bab, bba)))))))))
-@version:Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(1), Text(.)))), Text(0, 09/07/2012))))))
-@since:Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(2), Text(.)))), Text(10))))))
-@todo:
-@note:
-@see:
-body:Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(This is a test comment), Text(.)))), Text(
-))))))
-@example:Body(List(Paragraph(Chain(List(Summary(Monospace(Text("abb".permutations = Iterator(abb, bab, bba)))))))))
-@version:Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(1), Text(.)))), Text(0, 09/07/2012))))))
-@since:Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(2), Text(.)))), Text(10))))))
-@todo:Body(List(Paragraph(Chain(List(Summary(Text(this method is unsafe)))))))
-@note:
-@see:
-body:Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(This is a test comment), Text(.)))), Text(
-))))))
-@example:Body(List(Paragraph(Chain(List(Summary(Monospace(Text("abb".permutations = Iterator(abb, bab, bba)))))))))
-@version:Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(1), Text(.)))), Text(0, 09/07/2012))))))
-@since:Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(2), Text(.)))), Text(10))))))
-@todo:Body(List(Paragraph(Chain(List(Summary(Text(this method is unsafe)))))))
-@note:Body(List(Paragraph(Chain(List(Summary(Text(Don't inherit!)))))))
-@see:
-body:Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(This is a test comment), Text(.)))), Text(
-))))))
-@example:Body(List(Paragraph(Chain(List(Summary(Monospace(Text("abb".permutations = Iterator(abb, bab, bba)))))))))
-@version:Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(1), Text(.)))), Text(0, 09/07/2012))))))
-@since:Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(2), Text(.)))), Text(10))))))
-@todo:Body(List(Paragraph(Chain(List(Summary(Text(this method is unsafe)))))))
-@note:Body(List(Paragraph(Chain(List(Summary(Text(Don't inherit!)))))))
-@see:Body(List(Paragraph(Chain(List(Summary(Text(some other method)))))))
+reload: Base.scala, Class.scala, Derived.scala
diff --git a/test/files/presentation/doc/doc.scala b/test/files/presentation/doc/doc.scala
index 5855f488b8..371b825026 100755
--- a/test/files/presentation/doc/doc.scala
+++ b/test/files/presentation/doc/doc.scala
@@ -4,27 +4,40 @@ import scala.tools.nsc.doc.base.comment._
 import scala.tools.nsc.interactive._
 import scala.tools.nsc.interactive.tests._
 import scala.tools.nsc.util._
-import scala.tools.nsc.io._
 
 object Test extends InteractiveTest {
   val tags = Seq(
     "@example  `\"abb\".permutations = Iterator(abb, bab, bba)`",
     "@version 1.0, 09/07/2012",
     "@since 2.10",
-    "@todo this method is unsafe",
+    "@todo this is unsafe!",
     "@note Don't inherit!",
-    "@see some other method"
+    "@see something else"
   )
 
-  val comment = "This is a test comment."
-  val caret = "<caret>"
+  val names = Seq("Class", "Def", "Val", "Var", "AbstracType", "TypeAlias", "Trait", "InnerClass")
+  val bareText =
+    """abstract class %s {
+    |  def %s = ""
+    |  val %s = ""
+    |  var %s: String = _
+    |  type %s
+    |  type %s = String
+    |  class %s
+    |}
+    |trait %s""".stripMargin.format(names: _*)
+
+  def docComment(nTags: Int) = "/**\n%s*/".format(tags.take(nTags).mkString("\n"))
+
+  def text(name: String, nTags: Int) = {
+    val nameIndex = bareText.indexOf(name)
+    val (pre, post) = bareText.splitAt(nameIndex)
+    val crIndex = pre.lastIndexOf("\n")
+    val (prepre, prepost) = pre.splitAt(crIndex)
+    prepre + docComment(nTags) + prepost + post
+  }
+
 
-  def text(nTags: Int) = 
-    """|/** %s
-       |
-       | *  %s */
-       |trait Commented {}
-       |class User(c: %sCommented)""".stripMargin.format(comment, tags take nTags mkString "\n", caret)
 
   override lazy val compiler = {
     prepareSettings(settings)
@@ -38,9 +51,9 @@ object Test extends InteractiveTest {
 
       override def forScaladoc = true
 
-      def getComment(sym: Symbol, source: SourceFile) = {
+      def getComment(sym: Symbol, source: SourceFile, fragments: List[(Symbol,SourceFile)]): Option[Comment] = {
         val docResponse = new Response[(String, String, Position)]
-        askDocComment(sym, sym.owner, source, docResponse)
+        askDocComment(sym, source, sym.owner, fragments, docResponse)
         docResponse.get.left.toOption flatMap {
           case (expanded, raw, pos) =>
             if (expanded.isEmpty)
@@ -53,37 +66,74 @@ object Test extends InteractiveTest {
   }
 
   override def runDefaultTests() {
-    for (i <- 1 to tags.length) {
-      val markedText = text(i)
-      val idx = markedText.indexOf(caret)
-      val fileText = markedText.substring(0, idx) + markedText.substring(idx + caret.length)
-      val source = sourceFiles(0) 
-      val batch = new BatchSourceFile(source.file, fileText.toCharArray)
+    import compiler._
+    def findSource(name: String) = sourceFiles.find(_.file.name == name).get
+
+    val className = names.head
+    for (name <- names;
+         i <- 1 to tags.length) {
+      val newText = text(name, i)
+      val source = findSource("Class.scala")
+      val batch = new BatchSourceFile(source.file, newText.toCharArray)
       val reloadResponse = new Response[Unit]
       compiler.askReload(List(batch), reloadResponse)
       reloadResponse.get.left.toOption match {
         case None =>
-          reporter.println("Couldn't reload")
+          println("Couldn't reload")
         case Some(_) =>
-          val treeResponse = new compiler.Response[compiler.Tree]
-          val pos = compiler.rangePos(batch, idx, idx, idx)
-          compiler.askTypeAt(pos, treeResponse)
-          treeResponse.get.left.toOption match {
-            case Some(tree) =>
-              val sym = tree.tpe.typeSymbol
-              compiler.getComment(sym, batch) match {
-                case None => println("Got no doc comment")
+          val parseResponse = new Response[Tree]
+          askParsedEntered(batch, true, parseResponse)
+          parseResponse.get.left.toOption match {
+            case None =>
+              println("Couldn't parse")
+            case Some(_) =>
+              val sym = compiler.ask { () =>
+                val toplevel = definitions.EmptyPackage.info.decl(newTypeName(name))
+                if (toplevel eq NoSymbol) {
+                  val clazz = definitions.EmptyPackage.info.decl(newTypeName(className))
+
+                  val term = clazz.info.decl(newTermName(name))
+                  if (term eq NoSymbol) clazz.info.decl(newTypeName(name)) else
+                    if (term.isAccessor) term.accessed else term
+                } else toplevel
+              }
+
+              getComment(sym, batch, (sym,batch)::Nil) match {
+                case None => println(s"Got no doc comment for $name")
                 case Some(comment) =>
                   import comment._
-                  val tags: List[(String, Iterable[Body])] =
-                    List(("@example", example), ("@version", version), ("@since", since.toList), ("@todo", todo), ("@note",  note), ("@see", see))
-                  val str = ("body:" + body + "\n") + 
-                    tags.map{ case (name, bodies) => name + ":" + bodies.mkString("\n") }.mkString("\n")
-                  println(str)
+                  def cnt(bodies: Iterable[Body]) = bodies.size
+                  val actual = cnt(example) + cnt(version) + cnt(since) + cnt(todo) + cnt(note) + cnt(see)
+                  if (actual != i)
+                    println(s"Got docComment with $actual tags instead of $i, file text:\n$newText")
               }
-            case None => println("Couldn't find a typedTree")
           }
       }
     }
+
+    // Check inter-classes documentation one-time retrieved ok.
+    val baseSource = findSource("Base.scala")
+    val derivedSource = findSource("Derived.scala")
+    def existsText(where: Any, text: String): Boolean = where match {
+      case `text` => true
+      case s: Seq[_] => s exists (existsText(_, text))
+      case p: Product => p.productIterator exists (existsText(_, text))
+    }
+    val (derived, base) = compiler.ask { () => 
+      val derived = definitions.RootPackage.info.decl(newTermName("p")).info.decl(newTypeName("Derived"))
+      (derived, derived.ancestors(0))
+    }
+    val cmt1 = getComment(derived, derivedSource, (base, baseSource)::(derived, derivedSource)::Nil)
+    if (!existsText(cmt1, "Derived comment."))
+      println("Unexpected Derived class comment:"+cmt1)
+
+    val (fooDerived, fooBase) = compiler.ask { () =>
+      val decl = derived.tpe.decl(newTermName("foo"))
+      (decl, decl.allOverriddenSymbols(0))
+    }
+
+    val cmt2 = getComment(fooDerived, derivedSource, (fooBase, baseSource)::(fooDerived, derivedSource)::Nil)
+    if (!existsText(cmt2, "Base method has documentation."))
+      println("Unexpected foo method comment:"+cmt2)
   }
 }
diff --git a/test/files/presentation/doc/src/Class.scala b/test/files/presentation/doc/src/Class.scala
new file mode 100755
index 0000000000..a974bd6f5c
--- /dev/null
+++ b/test/files/presentation/doc/src/Class.scala
@@ -0,0 +1 @@
+object Class
\ No newline at end of file
diff --git a/test/files/presentation/doc/src/Test.scala b/test/files/presentation/doc/src/Test.scala
deleted file mode 100755
index fcc1554994..0000000000
--- a/test/files/presentation/doc/src/Test.scala
+++ /dev/null
@@ -1 +0,0 @@
-object Test
\ No newline at end of file
diff --git a/test/files/presentation/doc/src/p/Base.scala b/test/files/presentation/doc/src/p/Base.scala
new file mode 100755
index 0000000000..9031de3e3e
--- /dev/null
+++ b/test/files/presentation/doc/src/p/Base.scala
@@ -0,0 +1,11 @@
+package p
+
+/**
+ * @define BaseComment $BaseVar comment.
+ */
+trait Base {
+  /**
+   * Base method has documentation.
+   */
+  def foo: String
+}
diff --git a/test/files/presentation/doc/src/p/Derived.scala b/test/files/presentation/doc/src/p/Derived.scala
new file mode 100755
index 0000000000..1a9c9a26d1
--- /dev/null
+++ b/test/files/presentation/doc/src/p/Derived.scala
@@ -0,0 +1,9 @@
+package p
+
+/**
+ * $BaseComment
+ * @define BaseVar Derived
+ */
+class Derived extends Base {
+  def foo = ""
+}