Changed the way use cases are handled in scaladoc.

If use cases are present, the original member disappears from the list.
References SI-5054, but needs more work on the html part. If use cases
are present along with links, scaladoc doesn't crash anymore. Closes
SI-4898.

Review by kzys.

5 files changed, 55 insertions, 3 deletions

diff --git a/src/compiler/scala/tools/nsc/doc/model/Entity.scala b/src/compiler/scala/tools/nsc/doc/model/Entity.scala
index 42f0f67fa7..266b9294dd 100644
--- a/src/compiler/scala/tools/nsc/doc/model/Entity.scala
+++ b/src/compiler/scala/tools/nsc/doc/model/Entity.scala
@@ -301,6 +301,10 @@ trait NonTemplateMemberEntity extends MemberEntity {
     * It corresponds to a real member, and provides a simplified, yet compatible signature for that member. */
   def isUseCase: Boolean
 
+  /** If this symbol is a use case, the useCaseOf will contain the member it was derived from, containing the full
+    * signature and the complete parameter descriptions. */
+  def useCaseOf: Option[MemberEntity]
+
   /** Whether this member is a bridge member. A bridge member does only exist for binary compatibility reasons
     * and should not appear in ScalaDoc. */
   def isBridge: Boolean
diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala
index 1efcbeac29..a3b4dc4337 100644
--- a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala
+++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala
@@ -453,16 +453,18 @@ class ModelFactory(val global: Global, val settings: doc.Settings) {
   /** */
   def makeMember(aSym: Symbol, inTpl: => DocTemplateImpl): List[MemberImpl] = {
 
-    def makeMember0(bSym: Symbol): Option[MemberImpl] = {
+    def makeMember0(bSym: Symbol, _useCaseOf: Option[MemberImpl]): Option[MemberImpl] = {
       if (bSym.isGetter && bSym.isLazy)
           Some(new NonTemplateMemberImpl(bSym, inTpl) with Val {
             override lazy val comment = // The analyser does not duplicate the lazy val's DocDef when it introduces its accessor.
               thisFactory.comment(bSym.accessed, inTpl) // This hack should be removed after analyser is fixed.
             override def isLazyVal = true
+            override def useCaseOf = _useCaseOf
           })
       else if (bSym.isGetter && bSym.accessed.isMutable)
         Some(new NonTemplateMemberImpl(bSym, inTpl) with Val {
           override def isVar = true
+          override def useCaseOf = _useCaseOf
         })
       else if (bSym.isMethod && !bSym.hasAccessorFlag && !bSym.isConstructor && !bSym.isModule) {
         val cSym = { // This unsightly hack closes issue #4086.
@@ -478,25 +480,30 @@ class ModelFactory(val global: Global, val settings: doc.Settings) {
         }
         Some(new NonTemplateParamMemberImpl(cSym, inTpl) with HigherKindedImpl with Def {
           override def isDef = true
+          override def useCaseOf = _useCaseOf
         })
       }
       else if (bSym.isConstructor)
         Some(new NonTemplateParamMemberImpl(bSym, inTpl) with Constructor {
           override def isConstructor = true
           def isPrimary = sym.isPrimaryConstructor
+          override def useCaseOf = _useCaseOf
         })
       else if (bSym.isGetter) // Scala field accessor or Java field
         Some(new NonTemplateMemberImpl(bSym, inTpl) with Val {
           override def isVal = true
+          override def useCaseOf = _useCaseOf
         })
       else if (bSym.isAbstractType)
         Some(new NonTemplateMemberImpl(bSym, inTpl) with TypeBoundsImpl with HigherKindedImpl with AbstractType {
           override def isAbstractType = true
+          override def useCaseOf = _useCaseOf
         })
       else if (bSym.isAliasType)
         Some(new NonTemplateMemberImpl(bSym, inTpl) with HigherKindedImpl with AliasType {
           override def isAliasType = true
           def alias = makeTypeInTemplateContext(sym.tpe.dealias, inTpl, sym)
+          override def useCaseOf = _useCaseOf
         })
       else if (bSym.isPackage)
         inTpl match { case inPkg: PackageImpl =>  makePackage(bSym, inPkg) }
@@ -510,9 +517,16 @@ class ModelFactory(val global: Global, val settings: doc.Settings) {
       Nil
     else {
       val allSyms = useCases(aSym, inTpl.sym) map { case (bSym, bComment, bPos) =>
-        addCommentBody(bSym, inTpl, bComment, bPos)
+      	docComments.put(bSym, DocComment(bComment, bPos)) // put the comment in the list, don't parse it yet, closes SI-4898
+        bSym
       }
-      (allSyms :+ aSym) flatMap { makeMember0(_) }
+
+      val member = makeMember0(aSym, None)
+  		if (allSyms.isEmpty)
+  			member.toList
+    	else
+    		// Use cases replace the original definitions - SI-5054
+    		allSyms flatMap { makeMember0(_, member) }
     }
 
   }
diff --git a/test/scaladoc/resources/SI_4898.scala b/test/scaladoc/resources/SI_4898.scala
new file mode 100644
index 0000000000..40461d15b5
--- /dev/null
+++ b/test/scaladoc/resources/SI_4898.scala
@@ -0,0 +1,9 @@
+class SI_4898 {
+	
+	/**
+	 * A link to [[__root__
+	 * 
+	 * @usecase def test(): Int
+	 */
+	def test(implicit param: Int): Int = param
+}
\ No newline at end of file
diff --git a/test/scaladoc/resources/SI_5054.scala b/test/scaladoc/resources/SI_5054.scala
new file mode 100644
index 0000000000..17167303e4
--- /dev/null
+++ b/test/scaladoc/resources/SI_5054.scala
@@ -0,0 +1,10 @@
+class SI_5054 {
+	
+	/**
+	 * A simple comment
+	 * 
+	 * @param lost a lost parameter
+	 * @usecase def test(): Int
+	 */
+	def test(implicit lost: Int): Int = lost
+}
\ No newline at end of file
diff --git a/test/scaladoc/scala/html/HtmlFactoryTest.scala b/test/scaladoc/scala/html/HtmlFactoryTest.scala
index 916fe2e42f..adad3b6053 100644
--- a/test/scaladoc/scala/html/HtmlFactoryTest.scala
+++ b/test/scaladoc/scala/html/HtmlFactoryTest.scala
@@ -373,6 +373,21 @@ object Test extends Properties("HtmlFactory") {
     }
   }
 
+  property("Use cases and links should not crash scaladoc") = {
+    createTemplate("SI_4898.scala")
+    true
+  }
+
+  property("Use cases should override their original members - valid until signature is added to html") = {
+    createTemplate("SI_5054.scala") match {
+      case node: scala.xml.Node =>
+        node.toString.contains("A simple comment") &&
+        ! node.toString.contains("a lost parameter")
+      case _ => false
+    }
+  }
+
+  
   {
     val files = createTemplates("basic.scala")
     println(files)