From 97b0af746ac3f2eb2fe7078b5aa5d596439fbfb5 Mon Sep 17 00:00:00 2001
From: Thiago Pereira <thiago@Thiagos-Mac-mini.local>
Date: Sun, 23 Oct 2016 21:19:00 -0200
Subject: Add error message - Comments.scala:128

This commit adds the semantic object for the ```definition not found``` error.
It is part of the (https://github.com/lampepfl/dotty/issues/1589)[https://github.com/lampepfl/dotty/issues/1589]
---
 src/dotty/tools/dotc/core/Comments.scala           |  3 +-
 .../tools/dotc/reporting/diagnostic/messages.scala | 39 +++++++++++++++++++++-
 2 files changed, 40 insertions(+), 2 deletions(-)

(limited to 'src')

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
+    }
+  }
+
 }
-- 
cgit v1.2.3