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.

2 files changed, 98 insertions, 0 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
+}