Fixed #5054, #5287

The documents with use cases should be restructured like:

  /**
   * The full definition, either used with an implicit value or with an explicit one.
   *
   * Some more explanation on implicits...
   *
   * @param lost a lost parameter
   * @return some integer
   *
   * @usecase def test(): Int
   *
   * This takes the implicit value in scope.
   *
   * Example: `test()`
   *
   * @usecase def test(explicit: Int): Int
   *
   * This takes the explicit value passed.
   *
   * Example: `test(3)`
   */
  def test(implicit lost: Int): Int

11 files changed, 186 insertions, 23 deletions

diff --git a/src/compiler/scala/tools/nsc/ast/DocComments.scala b/src/compiler/scala/tools/nsc/ast/DocComments.scala
index 9c598bca41..8d52a7bd2c 100755
--- a/src/compiler/scala/tools/nsc/ast/DocComments.scala
+++ b/src/compiler/scala/tools/nsc/ast/DocComments.scala
@@ -101,7 +101,7 @@ trait DocComments { self: Global =>
     def getUseCases(dc: DocComment) = {
       for (uc <- dc.useCases; defn <- uc.expandedDefs(site)) yield
         (defn,
-         expandVariables(merge(cookedDocComment(sym), uc.comment.raw, defn, copyFirstPara = true), sym, site),
+         expandVariables(merge(cookedDocComment(sym), uc.comment.raw, defn), sym, site),
          uc.pos)
     }
     getDocComment(sym) map getUseCases getOrElse List()
diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala
index a3b4dc4337..1fe96ed447 100644
--- a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala
+++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala
@@ -119,14 +119,18 @@ class ModelFactory(val global: Global, val settings: doc.Settings) {
         else Public()
       }
     }
-    def flags = {
-      val fgs = mutable.ListBuffer.empty[Paragraph]
-      if (sym.isImplicit) fgs += Paragraph(Text("implicit"))
-      if (sym.isSealed) fgs += Paragraph(Text("sealed"))
-      if (!sym.isTrait && (sym hasFlag Flags.ABSTRACT)) fgs += Paragraph(Text("abstract"))
-      if (!sym.isTrait && (sym hasFlag Flags.DEFERRED)) fgs += Paragraph(Text("abstract"))
-      if (!sym.isModule && (sym hasFlag Flags.FINAL)) fgs += Paragraph(Text("final"))
-      fgs.toList
+    def flags = this match { 
+      	// workaround for uninitialized flags in use cases - see SI-5054
+    		case m: NonTemplateMemberEntity if (m.useCaseOf.isDefined) =>
+    			m.useCaseOf.get.flags
+    		case _ =>
+		      val fgs = mutable.ListBuffer.empty[Paragraph]
+		      if (sym.isImplicit) fgs += Paragraph(Text("implicit"))
+		      if (sym.isSealed) fgs += Paragraph(Text("sealed"))
+		      if (!sym.isTrait && (sym hasFlag Flags.ABSTRACT)) fgs += Paragraph(Text("abstract"))
+		      if (!sym.isTrait && (sym hasFlag Flags.DEFERRED)) fgs += Paragraph(Text("abstract"))
+		      if (!sym.isModule && (sym hasFlag Flags.FINAL)) fgs += Paragraph(Text("final"))
+		      fgs.toList    	
     }
     def deprecation =
       if (sym.isDeprecated)
diff --git a/test/scaladoc/resources/SI_5054.scala b/test/scaladoc/resources/SI_5054.scala
deleted file mode 100644
index 17167303e4..0000000000
--- a/test/scaladoc/resources/SI_5054.scala
+++ /dev/null
@@ -1,10 +0,0 @@
-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/resources/SI_5054_q1.scala b/test/scaladoc/resources/SI_5054_q1.scala
new file mode 100644
index 0000000000..02d9be8dd0
--- /dev/null
+++ b/test/scaladoc/resources/SI_5054_q1.scala
@@ -0,0 +1,9 @@
+class SI_5054_q1 {
+  /**
+    * A simple comment
+    * 
+    * @param lost a lost parameter
+    * @usecase def test(): Int
+    */
+   def test(implicit lost: Int): Int = lost
+}
diff --git a/test/scaladoc/resources/SI_5054_q2.scala b/test/scaladoc/resources/SI_5054_q2.scala
new file mode 100644
index 0000000000..c873731e5b
--- /dev/null
+++ b/test/scaladoc/resources/SI_5054_q2.scala
@@ -0,0 +1,9 @@
+class SI_5054_q2 {
+  /**
+    * A simple comment
+    * 
+    * @param lost a lost parameter
+    * @usecase def test(): Int
+    */
+   final def test(implicit lost: Int): Int = lost
+}
diff --git a/test/scaladoc/resources/SI_5054_q3.scala b/test/scaladoc/resources/SI_5054_q3.scala
new file mode 100644
index 0000000000..be5d22ffdc
--- /dev/null
+++ b/test/scaladoc/resources/SI_5054_q3.scala
@@ -0,0 +1,9 @@
+class SI_5054_q3 {
+  /**
+    * A simple comment
+    * 
+    * @param lost a lost parameter
+    * @usecase def test(): Int
+    */
+   implicit def test(implicit lost: Int): Int = lost
+}
diff --git a/test/scaladoc/resources/SI_5054_q4.scala b/test/scaladoc/resources/SI_5054_q4.scala
new file mode 100644
index 0000000000..4e5e4865f1
--- /dev/null
+++ b/test/scaladoc/resources/SI_5054_q4.scala
@@ -0,0 +1,9 @@
+abstract class SI_5054_q4 {
+  /**
+    * A simple comment
+    * 
+    * @param lost a lost parameter
+    * @usecase def test(): Int
+    */
+   def test(implicit lost: Int): Int
+}
diff --git a/test/scaladoc/resources/SI_5054_q5.scala b/test/scaladoc/resources/SI_5054_q5.scala
new file mode 100644
index 0000000000..05ba7488eb
--- /dev/null
+++ b/test/scaladoc/resources/SI_5054_q5.scala
@@ -0,0 +1,9 @@
+trait SI_5054_q5 {
+  /**
+    * A simple comment
+    * 
+    * @param lost a lost parameter
+    * @usecase def test(): Int
+    */
+   def test(implicit lost: Int): Int = lost
+}
diff --git a/test/scaladoc/resources/SI_5054_q6.scala b/test/scaladoc/resources/SI_5054_q6.scala
new file mode 100644
index 0000000000..607be654a5
--- /dev/null
+++ b/test/scaladoc/resources/SI_5054_q6.scala
@@ -0,0 +1,9 @@
+trait SI_5054_q6 {
+  /**
+    * A simple comment
+    * 
+    * @param lost a lost parameter
+    * @usecase def test(): Int
+    */
+   def test(implicit lost: Int): Int
+}
diff --git a/test/scaladoc/resources/SI_5054_q7.scala b/test/scaladoc/resources/SI_5054_q7.scala
new file mode 100644
index 0000000000..26d4b5fcf4
--- /dev/null
+++ b/test/scaladoc/resources/SI_5054_q7.scala
@@ -0,0 +1,22 @@
+trait SI_5054_q7 {
+  /**
+   * The full definition, either used with an implicit value or with an explicit one.
+   *
+   * Some more explanation on implicits...
+   *
+   * @param lost a lost parameter
+   * @return some integer
+   * @usecase def test(): Int
+   *
+   * This takes the implicit value in scope.
+   *
+   * Example: `test()`
+   * 
+   * @usecase def test(explicit: Int): Int
+   * 
+   * This takes the explicit value passed.
+   *
+   * Example: `test(3)`
+   */
+  def test(implicit lost: Int): Int
+}
diff --git a/test/scaladoc/scala/html/HtmlFactoryTest.scala b/test/scaladoc/scala/html/HtmlFactoryTest.scala
index c8dad4cf48..d1bfbb023f 100644
--- a/test/scaladoc/scala/html/HtmlFactoryTest.scala
+++ b/test/scaladoc/scala/html/HtmlFactoryTest.scala
@@ -378,15 +378,108 @@ object Test extends Properties("HtmlFactory") {
     true
   }
 
-  property("Use cases should override their original members - valid until signature is added to html") = {
-    createTemplate("SI_5054.scala") match {
+  // A piece of the signature - corresponding to the use case
+  def signature(no: Int, modifier: String) = ("""
+    <li visbl="pub" name="SI_5054_q""" + no + """#test" data-isabs="false">
+      <a id="test():Int"></a>
+      <h4 class="signature">
+      <span class="modifier_kind">
+        <span class="modifier">""" + modifier + """</span>
+        <span class="kind">def</span>
+      </span>
+      <span class="symbol">
+        <span class="name">test</span><span class="params">()</span><span class="result">: <span name="scala.Int" class="extype">Int</span></span>
+      </span>
+      </h4>
+      <p class="shortcomment cmt">[use case]
+      </p>
+    </li>""").replaceAll("\\s+", "")
+  
+  property("Use cases should override their original members") = {
+    createTemplate("SI_5054_q1.scala") match {
+      case node: scala.xml.Node =>
+        node.toString.replaceAll("\\s+","").contains(signature(1, ""))
+      case _ => false
+    }
+  }
+
+  property("Use cases should keep their flags - final should not be lost") = {
+    createTemplate("SI_5054_q2.scala") match {
+      case node: scala.xml.Node =>
+        node.toString.replaceAll("\\s+","").contains(signature(2, "final"))
+      case _ => false
+    }
+  }
+  
+  property("Use cases should keep their flags - implicit should not be lost") = {
+    createTemplate("SI_5054_q3.scala") match {
+      case node: scala.xml.Node =>
+        node.toString.replaceAll("\\s+","").contains(signature(3, "implicit"))
+      case _ => false
+    }
+  }
+
+  property("Use cases should keep their flags - real abstract should not be lost") = {
+    createTemplate("SI_5054_q4.scala") match {
+      case node: scala.xml.Node =>
+        node.toString.replaceAll("\\s+","").contains(signature(4, "abstract"))
+      case _ => false
+    }
+  }
+
+  property("Use cases should keep their flags - traits should not be affected") = {
+    createTemplate("SI_5054_q5.scala") match {
       case node: scala.xml.Node =>
-        node.toString.contains("A simple comment") &&
-        ! node.toString.contains("a lost parameter")
+        node.toString.replaceAll("\\s+","").contains(signature(5, ""))
       case _ => false
     }
   }
 
+  property("Use cases should keep their flags - traits should not be affected") = {
+    createTemplate("SI_5054_q6.scala") match {
+      case node: scala.xml.Node =>
+        node.toString.replaceAll("\\s+","").contains(signature(6, "abstract"))
+      case _ => false
+    }
+  }
+  
+  val useCaseExplanation = """
+   </li><li visbl="pub" name="SI_5054_q7#test" data-isabs="false">
+      <a id="test():Int"></a>
+      <h4 class="signature">
+      <span class="modifier_kind">
+        <span class="modifier">abstract </span>
+        <span class="kind">def</span>
+      </span>
+      <span class="symbol">
+        <span class="name">test</span><span class="params">()</span><span class="result">: <span name="scala.Int" class="extype">Int</span></span>
+      </span>
+      </h4>
+      <p class="shortcomment cmt">[use case] This takes the implicit value in scope.</p><div class="fullcomment">[use case] <div class="comment cmt"><p>This takes the implicit value in scope.</p><p>Example: <code>test()</code></p></div><dl class="paramcmts block"><dt>returns</dt><dd class="cmt"><p>some integer
+   </p></dd></dl></div>
+    </li><li visbl="pub" name="SI_5054_q7#test" data-isabs="false">
+      <a id="test(Int):Int"></a>
+      <h4 class="signature">
+      <span class="modifier_kind">
+        <span class="modifier">abstract </span>
+        <span class="kind">def</span>
+      </span>
+      <span class="symbol">
+        <span class="name">test</span><span class="params">(<span name="explicit">explicit: <span name="scala.Int" class="extype">Int</span></span>)</span><span class="result">: <span name="scala.Int" class="extype">Int</span></span>
+      </span>
+      </h4>
+      <p class="shortcomment cmt">[use case] This takes the explicit value passed.</p><div class="fullcomment">[use case] <div class="comment cmt"><p>This takes the explicit value passed.</p><p>Example: <code>test(3)</code></p></div><dl class="paramcmts block"><dt>returns</dt><dd class="cmt"><p>some integer
+   </p></dd></dl></div>
+    </li>
+  """.replaceAll("\\s+","")
+ 
+  property("Use case individual signature test") = {
+    createTemplate("SI_5054_q7.scala") match {
+      case node: scala.xml.Node =>
+        node.toString.replaceAll("\\s+","").contains(useCaseExplanation)
+      case _ => false
+    }
+  }
   
   {
     val files = createTemplates("basic.scala")