Scaladoc @usecase annotation overriding / SI-5287

From now on, the usecases inherit the comments from their parents, such
as the explanation and the annotations: @param, @tparam, @return, etc.
An example of usecase comment inheritance is:

  /**
   * The test function tests the parameter param for ...
   *
   * @param theParam the implicit parameter to be tested for ...
   * @return the result of the test
   *
   *
   *
   * @usecase def test(): Bool
   *
   * The test function tests the parameter taken implicitly from scope.
   * Example: `test()`
   *
   * @return the result of the test for the current scope
   *
   *
   *
   * @usecase def test(theParam: SomeType): Bool
   *
   * This takes the explicit value passed.
   * Example: `test(3)`
   *
   * @param theParam the explicit parameter to be tested for ...
   */
  def test(implicit theParam: SomeType): Bool

Notice both usecases override the explanation with their own examples.
The first usecase also overrides the "@return" annotation while the 2nd
usecase overrides the "@param theParam" annotation. If they didn't
override the explanations and annotations, they would inherit the
values from the actual implementation, def test(implicit ...)

This will be followed by @inheritdoc, which enables more fine-grained
control over comment inheritance. The full explanation of using comment
inheritance and @inheritdoc and their interaction with variables is
given at https://wiki.scala-lang.org/display/SW/Tags+and+Annotations
in the "Comment inheritance" and "Inheritance Example" sections.

3 files changed, 253 insertions, 34 deletions

diff --git a/test/scaladoc/resources/implicit-inheritance-override.scala b/test/scaladoc/resources/implicit-inheritance-override.scala
new file mode 100644
index 0000000000..85b8e8d543
--- /dev/null
+++ b/test/scaladoc/resources/implicit-inheritance-override.scala
@@ -0,0 +1,41 @@
+// This tests the implicit comment inheritance capabilities of scaladoc for class inheritance (no $super, no @inheritdoc)
+class Base {
+  /**
+   * The base comment. And another sentence...
+   * 
+   * @param arg1 The T term comment
+   * @param arg2 The string comment
+   * @tparam T the type of the first argument
+   * @return The return comment
+   */ 
+  def function[T](arg1: T, arg2: String): Double = 0.0d
+}
+
+class DerivedA extends Base {
+  /**
+   * Overriding the comment, the params and returns comments should stay the same.
+   */
+  override def function[T](arg1: T, arg2: String): Double = 1.0d
+}
+
+class DerivedB extends Base {
+  /**
+   * @param arg1 The overridden T term comment
+   * @param arg2 The overridden string comment
+   */
+  override def function[T](arg1: T, arg2: String): Double = 2.0d
+}
+
+class DerivedC extends Base {
+  /**
+   * @return The overridden return comment
+   */
+  override def function[T](arg1: T, arg2: String): Double = 3.0d
+}
+
+class DerivedD extends Base {
+  /**
+   * @tparam T The overriden type parameter comment
+   */
+  override def function[T](arg1: T, arg2: String): Double = 3.0d
+}
\ No newline at end of file
diff --git a/test/scaladoc/resources/implicit-inheritance-usecase.scala b/test/scaladoc/resources/implicit-inheritance-usecase.scala
new file mode 100644
index 0000000000..8dd1262e4b
--- /dev/null
+++ b/test/scaladoc/resources/implicit-inheritance-usecase.scala
@@ -0,0 +1,57 @@
+// This tests the implicit comment inheritance capabilities of scaladoc for usecases (no $super, no @inheritdoc)
+/** Testing use case inheritance */
+class UseCaseInheritance {
+  /**
+   * The base comment. And another sentence...
+   * 
+   * @param arg1 The T term comment
+   * @param arg2 The string comment
+   * @tparam T The type parameter
+   * @return The return comment
+   *
+   * @usecase def missing_arg[T](arg1: T): Double
+   *
+   * @usecase def missing_targ(arg1: Int, arg2: String): Double
+   *
+   * @usecase def overridden_arg1[T](implicit arg1: T, arg2: String): Double
+   * @param arg1 The overridden T term comment
+   *
+   * @usecase def overridden_targ[T](implicit arg1: T, arg2: String): Double
+   * @tparam T The overridden type parameter comment
+   *
+   * @usecase def overridden_return[T](implicit arg1: T, arg2: String): Double
+   * @return The overridden return comment
+   *
+   * @usecase def added_arg[T](implicit arg1: T, arg2: String, arg3: Float): Double
+   * @param arg3 The added float comment
+   *
+   * @usecase def overridden_comment[T](implicit arg1: T, arg2: String): Double
+   * The overridden comment.
+   */ 
+  def function[T](implicit arg1: T, arg2: String): Double = 0.0d
+}
+
+/** Testing the override-use case interaction */
+class UseCaseOverrideInheritance extends UseCaseInheritance {
+  /**
+   * @usecase def missing_arg[T](arg1: T): Double
+   *
+   * @usecase def missing_targ(arg1: Int, arg2: String): Double
+   *
+   * @usecase def overridden_arg1[T](implicit arg1: T, arg2: String): Double
+   * @param arg1 The overridden T term comment
+   *
+   * @usecase def overridden_targ[T](implicit arg1: T, arg2: String): Double
+   * @tparam T The overridden type parameter comment
+   *
+   * @usecase def overridden_return[T](implicit arg1: T, arg2: String): Double
+   * @return The overridden return comment
+   *
+   * @usecase def added_arg[T](implicit arg1: T, arg2: String, arg3: Float): Double
+   * @param arg3 The added float comment
+   *
+   * @usecase def overridden_comment[T](implicit arg1: T, arg2: String): Double
+   * The overridden comment.
+   */ 
+  override def function[T](implicit arg1: T, arg2: String): Double = 0.0d
+} 
diff --git a/test/scaladoc/scala/html/HtmlFactoryTest.scala b/test/scaladoc/scala/html/HtmlFactoryTest.scala
index e2687dd510..37aa302ac7 100644
--- a/test/scaladoc/scala/html/HtmlFactoryTest.scala
+++ b/test/scaladoc/scala/html/HtmlFactoryTest.scala
@@ -84,12 +84,7 @@ object Test extends Properties("HtmlFactory") {
     val html = scala.stripSuffix(".scala") + ".html"
     createTemplates(scala)(html)
   }
-  
-  /**
-   * See checkTextOnly(scalaFile: String, checks: List[String])
-   */
-  def checkText1(scalaFile: String, check: String, debug: Boolean = true): Boolean = checkText(scalaFile, List(check), debug)
-  
+
   /**
    * This tests the text without the markup - ex:
    * 
@@ -111,20 +106,31 @@ object Test extends Properties("HtmlFactory") {
    * 
    * NOTE: Comparison is done ignoring all whitespace
    */
-  def checkText(scalaFile: String, checks: List[String], debug: Boolean = true): Boolean = {
+  def checkText(scalaFile: String, debug: Boolean = true)(checks: (Option[String], String, Boolean)*): Boolean = {
     val htmlFile = scalaFile.stripSuffix(".scala") + ".html"    
-    val htmlText = createTemplates(scalaFile)(htmlFile).text.replace('→',' ').replaceAll("\\s+","")
+    val htmlAllFiles = createTemplates(scalaFile)
     var result = true
     
-    for (check <- checks) {
-    	val checkText = check.replace('→',' ').replaceAll("\\s+","")
-    	val checkValue = htmlText.contains(checkText)
-    	if (debug && (!checkValue)) {
-    		Console.err.println("Check failed: ")
-    		Console.err.println("HTML: " + htmlText)
-    		Console.err.println("Check: " + checkText)
-    	}
-  		result &&= checkValue 
+    for ((fileHint, check, expected) <- checks) {
+      // resolve the file to be checked
+      val fileName = fileHint match {
+        case Some(file) => 
+          if (file endsWith ".html")
+            file
+          else
+            file + ".html"
+        case None =>
+          htmlFile
+      }
+      val fileText = htmlAllFiles(fileName).text.replace('→',' ').replaceAll("\\s+","")
+      val checkText = check.replace('→',' ').replaceAll("\\s+","")
+      val checkValue = fileText.contains(checkText) == expected
+      if (debug && (!checkValue)) {
+        Console.err.println("Check failed: ")
+        Console.err.println("HTML: " + fileText)
+        Console.err.println("Check: " + checkText)
+      }
+      result &&= checkValue 
     }
     
     result
@@ -426,40 +432,155 @@ object Test extends Properties("HtmlFactory") {
     createTemplate("SI_4898.scala")
     true
   }
-  
+ 
   property("Use cases should override their original members") =
-     checkText1("SI_5054_q1.scala", """def test(): Int""") &&
-     !checkText1("SI_5054_q1.scala", """def test(implicit lost: Int): Int""")
-  
+     checkText("SI_5054_q1.scala")(
+       (None,"""def test(): Int""", true),
+       (None,"""def test(implicit lost: Int): Int""", false)
+     )
 
   property("Use cases should keep their flags - final should not be lost") = 
-    checkText1("SI_5054_q2.scala", """final def test(): Int""")
+    checkText("SI_5054_q2.scala")((None, """final def test(): Int""", true))
   
   property("Use cases should keep their flags - implicit should not be lost") = 
-    checkText1("SI_5054_q3.scala", """implicit def test(): Int""")
-
+    checkText("SI_5054_q3.scala")((None, """implicit def test(): Int""", true))
+ 
   property("Use cases should keep their flags - real abstract should not be lost") = 
-    checkText1("SI_5054_q4.scala", """abstract def test(): Int""")
+    checkText("SI_5054_q4.scala")((None, """abstract def test(): Int""", true))
 
   property("Use cases should keep their flags - traits should not be affected") = 
-    checkText1("SI_5054_q5.scala", """def test(): Int""")
+    checkText("SI_5054_q5.scala")((None, """def test(): Int""", true))
 
   property("Use cases should keep their flags - traits should not be affected") = 
-    checkText1("SI_5054_q6.scala", """abstract def test(): Int""")
+    checkText("SI_5054_q6.scala")((None, """abstract def test(): Int""", true))
    
   property("Use case individual signature test") = 
-    checkText("SI_5054_q7.scala", List( 
-        """abstract def test2(explicit: Int): Int [use case] This takes the explicit value passed.""",
-        """abstract def test1(): Int [use case] This takes the implicit value in scope."""))
+    checkText("SI_5054_q7.scala")(
+      (None, """abstract def test2(explicit: Int): Int [use case] This takes the explicit value passed.""", true),
+      (None, """abstract def test1(): Int [use case] This takes the implicit value in scope.""", true)
+    )
 
   property("Display correct \"Definition classes\"") = 
-    checkText1("SI_5287.scala", 
-        """def method(): Int
+    checkText("SI_5287.scala")( 
+      (None,
+          """def method(): Int
            [use case] The usecase explanation
            [use case] The usecase explanation
-           Definition Classes SI_5287 SI_5287_B SI_5287_A""", debug=true) 
-           // explanation appears twice, as small comment and full comment
+           Definition Classes SI_5287 SI_5287_B SI_5287_A""", true)
+    )      // the explanation appears twice, as small comment and full comment           
   
+    
+  property("Correct comment inheritance for overriding") = 
+    checkText("implicit-inheritance-override.scala")(
+      (Some("Base"), 
+       """def function[T](arg1: T, arg2: String): Double
+          The base comment.
+          The base comment. And another sentence...
+          T the type of the first argument
+          arg1 The T term comment
+          arg2 The string comment
+          returns The return comment
+          """, true),
+      (Some("DerivedA"), 
+       """def function[T](arg1: T, arg2: String): Double
+          Overriding the comment, the params and returns comments should stay the same.
+          Overriding the comment, the params and returns comments should stay the same.
+          T the type of the first argument
+          arg1 The T term comment
+          arg2 The string comment
+          returns The return comment
+          """, true),
+      (Some("DerivedB"), 
+       """def function[T](arg1: T, arg2: String): Double
+          T the type of the first argument
+          arg1 The overridden T term comment
+          arg2 The overridden string comment
+          returns The return comment
+          """, true),
+      (Some("DerivedC"), 
+       """def function[T](arg1: T, arg2: String): Double
+          T the type of the first argument
+          arg1 The T term comment
+          arg2 The string comment
+          returns The overridden return comment
+          """, true),
+      (Some("DerivedD"), 
+       """def function[T](arg1: T, arg2: String): Double
+          T The overriden type parameter comment
+          arg1 The T term comment
+          arg2 The string comment
+          returns The return comment
+          """, true)
+    )
+    
+  for (useCaseFile <- List("UseCaseInheritance", "UseCaseOverrideInheritance")) {
+    property("Correct comment inheritance for usecases") = 
+      checkText("implicit-inheritance-usecase.scala")(
+        (Some(useCaseFile), 
+         """def missing_arg[T](arg1: T): Double
+            [use case]
+            [use case]
+            T The type parameter
+            arg1 The T term comment
+            returns The return comment
+            """, true),
+        (Some(useCaseFile), 
+         """def missing_targ(arg1: Int, arg2: String): Double
+            [use case]
+            [use case]
+            arg1 The T term comment
+            arg2 The string comment
+            returns The return comment
+            """, true),
+        (Some(useCaseFile), 
+         """def overridden_arg1[T](implicit arg1: T, arg2: String): Double
+            [use case]
+            [use case]
+            T The type parameter
+            arg1 The overridden T term comment
+            arg2 The string comment
+            returns The return comment
+            """, true),
+        (Some(useCaseFile), 
+         """def overridden_targ[T](implicit arg1: T, arg2: String): Double
+            [use case]
+            [use case]
+            T The overridden type parameter comment
+            arg1 The T term comment
+            arg2 The string comment
+            returns The return comment
+            """, true),
+        (Some(useCaseFile), 
+         """def overridden_return[T](implicit arg1: T, arg2: String): Double
+            [use case]
+            [use case]
+            T The type parameter
+            arg1 The T term comment
+            arg2 The string comment
+            returns The overridden return comment
+            """, true),
+        (Some(useCaseFile), 
+         """def added_arg[T](implicit arg1: T, arg2: String, arg3: Float): Double
+            [use case]
+            [use case]
+            T The type parameter
+            arg1 The T term comment
+            arg2 The string comment
+            arg3 The added float comment
+            returns The return comment
+            """, true),
+        (Some(useCaseFile), 
+         """def overridden_comment[T](implicit arg1: T, arg2: String): Double
+            [use case] The overridden comment.
+            [use case] The overridden comment.
+            T The type parameter
+            arg1 The T term comment
+            arg2 The string comment
+            returns The return comment
+            """, true)
+      )    
+  }
+    
   {
     val files = createTemplates("basic.scala")
     //println(files)