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.

1 files changed, 24 insertions, 2 deletions

diff --git a/src/compiler/scala/tools/nsc/util/DocStrings.scala b/src/compiler/scala/tools/nsc/util/DocStrings.scala
index 1db6c38b4d..2c8b77be71 100755
--- 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 =