SI-5235 Correct usecase variable expansion

The bug is related to a couple of other annoyances, also fixed:
 - usecases without type params were crashing scaladoc due to a change
in the PolyTypes class (not allowing empty tparams list)
 - properly getting rid of backticks (even if the link is not valid)
 - correct linking for usecases with $Coll = `immutable.Seq`
(the symbol searching algorithm was too of restrictive, now we search
the entire ownerchain - and the empty package at the end)
 - give a warning if the type lookup fails
 - finally, added a $Coll variable to List, for some reason it wasn't
there and we were getting immutable.Seq as the result of use cases.

2 files changed, 91 insertions, 0 deletions

diff --git a/test/scaladoc/run/SI-5235.check b/test/scaladoc/run/SI-5235.check
new file mode 100644
index 0000000000..d9acfd063b
--- /dev/null
+++ b/test/scaladoc/run/SI-5235.check
@@ -0,0 +1,4 @@
+newSource:10: warning: Could not find the type $Coll points to while expanding it for the usecase signature of method reverse in trait SpecificColl.In this context, $Coll = "BullSh".
+             * @usecase def reverse(): $Coll
+                        ^
+Done.
diff --git a/test/scaladoc/run/SI-5235.scala b/test/scaladoc/run/SI-5235.scala
new file mode 100644
index 0000000000..cae70fd0a5
--- /dev/null
+++ b/test/scaladoc/run/SI-5235.scala
@@ -0,0 +1,87 @@
+import scala.tools.nsc.doc.model._
+import scala.tools.nsc.doc.model.diagram._
+import scala.tools.partest.ScaladocModelTest
+
+object Test extends ScaladocModelTest {
+
+  override def code = """
+        package scala.test.scaladoc.SI5235 {
+          trait Builder[From, To]
+
+          /**
+           * @define Coll `GenericColl`
+           */
+          class GenericColl {
+            /**
+             * @usecase def reverse(): $Coll
+             * Returns the reversed $Coll.
+             */
+            def reverse[T](implicit something: Builder[GenericColl, T]): T
+            def foo1: GenericColl = ???
+          }
+
+          /** Nooo, don't point to this */
+          trait MyCollection
+
+          package specific {
+            /**
+             * @define Coll `BullSh`
+             */
+            trait SpecificColl extends GenericColl {
+              def foo2: SpecificColl = ???
+            }
+          }
+
+          package mycoll {
+            /**
+             * @define Coll `mycoll.MyCollection`
+             */
+            class MyCollection extends specific.SpecificColl {
+              def foo3: MyCollection = ???
+            }
+          }
+        }
+    """
+
+  // diagrams must be started. In case there's an error with dot, it should not report anything
+  def scaladocSettings = ""
+
+  def testModel(rootPackage: Package) = {
+    // get the quick access implicit defs in scope (_package(s), _class(es), _trait(s), object(s) _method(s), _value(s))
+    import access._
+
+    val base = rootPackage._package("scala")._package("test")._package("scaladoc")._package("SI5235")
+
+    val GenericColl = base._class("GenericColl")
+    val SpecificColl = base._package("specific")._trait("SpecificColl")
+    val MyCollection = base._package("mycoll")._class("MyCollection")
+
+    // check comment text
+    val gcComment = extractCommentText(GenericColl._method("reverse").comment.get)
+    val scComment = extractCommentText(SpecificColl._method("reverse").comment.get)
+    val mcComment = extractCommentText(MyCollection._method("reverse").comment.get)
+    assert(gcComment.contains("Returns the reversed GenericColl."),
+           gcComment + ".contains(\"Returns the reversed GenericColl.\")")
+    assert(scComment.contains("Returns the reversed BullSh."),
+           scComment + ".contains(\"Returns the reversed BullSh.\")")
+    assert(mcComment.contains("Returns the reversed mycoll.MyCollection."),
+           mcComment + ".contains(\"Returns the reversed mycoll.MyCollection.\")")
+
+    // check signatures
+    val gcReverse = GenericColl._method("reverse")
+    val scReverse = SpecificColl._method("reverse")
+    val mcReverse = MyCollection._method("reverse")
+    val gcReverseType = gcReverse.resultType
+    val scReverseType = scReverse.resultType
+    val mcReverseType = mcReverse.resultType
+    assert(gcReverseType.name == "GenericColl", gcReverseType.name + " == GenericColl")
+    assert(scReverseType.name == "BullSh",      scReverseType.name + " == BullSh")
+    assert(mcReverseType.name == "MyCollection",mcReverseType.name + " == MyCollection")
+    assert(gcReverseType.refEntity(0)._1 == GenericColl,
+           gcReverse.qualifiedName + "'s return type has a link to " + GenericColl.qualifiedName)
+    assert(scReverseType.refEntity.isEmpty,
+           scReverse.qualifiedName + "'s return type does not have links")
+    assert(mcReverseType.refEntity(0)._1 == MyCollection,
+           mcReverse.qualifiedName + "'s return type has a link to " + MyCollection.qualifiedName)
+  }
+}
\ No newline at end of file