diff options
author | Vlad Ureche <vlad.ureche@gmail.com> | 2012-02-05 22:00:49 +0100 |
---|---|---|
committer | Vlad Ureche <vlad.ureche@gmail.com> | 2012-02-05 22:33:06 +0100 |
commit | 7946ac410ad74894cd0eb6dfd29447f173911b99 (patch) | |
tree | 2d2c7a8ecd4c5c2111b3e8d860210146927d7e5c /src | |
parent | 4bbfed3f8fda69624ea6a96de52ba973f55900cf (diff) | |
download | scala-7946ac410ad74894cd0eb6dfd29447f173911b99.tar.gz scala-7946ac410ad74894cd0eb6dfd29447f173911b99.tar.bz2 scala-7946ac410ad74894cd0eb6dfd29447f173911b99.zip |
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.
Diffstat (limited to 'src')
-rwxr-xr-x | src/compiler/scala/tools/nsc/util/DocStrings.scala | 26 |
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 = |