diff options
Diffstat (limited to 'src')
-rw-r--r-- | src/dotty/tools/dotc/core/Comments.scala | 3 | ||||
-rw-r--r-- | src/dotty/tools/dotc/reporting/diagnostic/messages.scala | 39 |
2 files changed, 40 insertions, 2 deletions
diff --git a/src/dotty/tools/dotc/core/Comments.scala b/src/dotty/tools/dotc/core/Comments.scala index 1cf5aec38..1e623db4d 100644 --- a/src/dotty/tools/dotc/core/Comments.scala +++ b/src/dotty/tools/dotc/core/Comments.scala @@ -9,6 +9,7 @@ import util.Positions._ import util.CommentParsing._ import util.Property.Key import parsing.Parsers.Parser +import reporting.diagnostic.messages.ProperDefinitionNotFound object Comments { val ContextDoc = new Key[ContextDocstrings] @@ -125,7 +126,7 @@ object Comments { val newName = (tree.name.show + "$" + codePos + "$doc").toTermName untpd.DefDef(newName, tree.tparams, tree.vparamss, tree.tpt, tree.rhs) case _ => - ctx.error("proper definition was not found in `@usecase`", codePos) + ctx.error(ProperDefinitionNotFound(), codePos) tree } } diff --git a/src/dotty/tools/dotc/reporting/diagnostic/messages.scala b/src/dotty/tools/dotc/reporting/diagnostic/messages.scala index 303ab0437..b0ce5b132 100644 --- a/src/dotty/tools/dotc/reporting/diagnostic/messages.scala +++ b/src/dotty/tools/dotc/reporting/diagnostic/messages.scala @@ -543,5 +543,42 @@ object messages { | |""".stripMargin } - + + case class ProperDefinitionNotFound()(implicit ctx: Context) extends Message(20) { + val kind = "Definition Not Found" + val msg = hl"""|Proper definition was not found in ${"@usecase"}""" + + val noUsecase = "def map[B, That](f: A => B)(implicit bf: CanBuildFrom[List[A], B, That]): That" + + val usecase = + """|/** Map from List[A] => List[B] + | * + | * @usecase def map[B](f: A => B): List[B] + | */ + |def map[B, That](f: A => B)(implicit bf: CanBuildFrom[List[A], B, That]): That""".stripMargin + + val explanation = { + hl"""|${"@usecase"} are only supported for ${"def"}s. They exist because with Scala's + |advanced type-system, we sometimes end up with seemingly scary signatures. + | + |Let's see an example using the `map`function: + | + |${"List(1, 2, 3).map(2 * _) // res: List(2, 4, 6)"} + | + |It's very straight forward to understand and use, but has such a scary signature: + | + |$noUsecase + | + |In order to mitigate this and ease the usage of such functions we have the ${"@usecase"} + |annotation for docstrings. Which can be used like this: + | + |$usecase + | + |Now when creating the docs, the method signature is substituted by the + |${"@usecase"} with a reader-friendly version. The compiler makes sure that it is valid. + | + |Because of this, you must use ${"def"} when defining ${"@usecase"}.""".stripMargin + } + } + } |