Fixed usecase @param/@tparam/@return overriding

which was not working at all previously
scala · VladUreche · Dec 16, 2011 · Dec 19, 2011 · Dec 19, 2011 · Dec 19, 2011
commit 6d1d197ab08ccd82dadd641fe64825a1e972d9d0
diff --git a/src/compiler/scala/tools/nsc/util/DocStrings.scala b/src/compiler/scala/tools/nsc/util/DocStrings.scala
@@ -71,13 +71,35 @@ object DocStrings {
    *  Every section starts with a `@` and extends to the next `@`, or
    *  to the end of the comment string, but excluding the final two
    *  characters which terminate the comment.
+   *  
+   *  Also take usecases into account - they need to expand until the next 
+   *  @usecase or the end of the string, as they might include other sections 
+   *  of their own 
    */
   def tagIndex(str: String, p: Int => Boolean = (idx => true)): List[(Int, Int)] =
     findAll(str, 0) (idx => str(idx) == '@' && p(idx)) match {
       case List() => List()
-      case idxs => idxs zip (idxs.tail ::: List(str.length - 2))
+      case idxs => {
+        val idxs2 = mergeUsecaseSections(str, idxs)
+        idxs2 zip (idxs2.tail ::: List(str.length - 2))
+      }
     }
-
+
+  /**
+   * Merge sections following an @usecase into the usecase comment, so they 
+   * can override the parent symbol's sections 
+   */
+  def mergeUsecaseSections(str: String, idxs: List[Int]): List[Int] = {
+    idxs.find(str.substring(_).startsWith("@usecase")) match {
+      case Some(firstUC) =>
+        val commentSections = idxs.take(idxs.indexOf(firstUC))
+        val usecaseSections = idxs.drop(idxs.indexOf(firstUC)).filter(str.substring(_).startsWith("@usecase"))
+        commentSections ::: usecaseSections
+      case None =>
+        idxs
+    }
+  }
+
   /** Does interval `iv` start with given `tag`?
    */
   def startsWithTag(str: String, section: (Int, Int), tag: String): Boolean =

diff --git a/test/scaladoc/scala/html/HtmlFactoryTest.scala b/test/scaladoc/scala/html/HtmlFactoryTest.scala
@@ -111,9 +111,9 @@ object Test extends Properties("HtmlFactory") {
     val htmlAllFiles = createTemplates(scalaFile)
     var result = true
 
-    for ((file, check, expected) <- checks) {
+    for ((fileHint, check, expected) <- checks) {
       // resolve the file to be checked
-      val fileName = file match {
+      val fileName = fileHint match {
         case Some(file) => 
           if (file endsWith ".html")
             file
@@ -122,7 +122,7 @@ object Test extends Properties("HtmlFactory") {
         case None =>
           htmlFile
       }
-      val fileText = htmlAllFiles(htmlFile).text.replace('→',' ').replaceAll("\\s+","")
+      val fileText = htmlAllFiles(fileName).text.replace('→',' ').replaceAll("\\s+","")
       val checkText = check.replace('→',' ').replaceAll("\\s+","")
       val checkValue = fileText.contains(checkText) == expected
       if (debug && (!checkValue)) {
@@ -436,15 +436,15 @@ object Test extends Properties("HtmlFactory") {
   property("Use cases should override their original members") =
      checkText("SI_5054_q1.scala")(
        (None,"""def test(): Int""", true),
-       (None,"""def test(implicit lost: Int): Int""", true)
+       (None,"""def test(implicit lost: Int): Int""", false)
      )
 
   property("Use cases should keep their flags - final should not be lost") = 
     checkText("SI_5054_q2.scala")((None, """final def test(): Int""", true))
 
   property("Use cases should keep their flags - implicit should not be lost") = 
     checkText("SI_5054_q3.scala")((None, """implicit def test(): Int""", true))
-
+ 
   property("Use cases should keep their flags - real abstract should not be lost") = 
     checkText("SI_5054_q4.scala")((None, """abstract def test(): Int""", true))
 
@@ -469,6 +469,119 @@ object Test extends Properties("HtmlFactory") {
            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)