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.

0 files changed, 0 insertions, 0 deletions