Improve documentation for message framework

3 files changed, 48 insertions, 10 deletions

diff --git a/src/dotty/tools/dotc/ast/Trees.scala b/src/dotty/tools/dotc/ast/Trees.scala
index 70701ecd7..0f9198b79 100644
--- a/src/dotty/tools/dotc/ast/Trees.scala
+++ b/src/dotty/tools/dotc/ast/Trees.scala
@@ -3,8 +3,8 @@ package dotc
 package ast
 
 import core._
-import Types._, Names._, Flags._, util.Positions._, Contexts._, Constants._, SymDenotations._, Symbols._
-import Denotations._, StdNames._, Comments._
+import Types._, Names._, Flags._, util.Positions._, Contexts._, Constants._
+import SymDenotations._, Symbols._, Denotations._, StdNames._, Comments._
 import annotation.tailrec
 import language.higherKinds
 import collection.IndexedSeqOptimized
diff --git a/src/dotty/tools/dotc/reporting/diagnostic/Message.scala b/src/dotty/tools/dotc/reporting/diagnostic/Message.scala
index 125ac2e1c..e365851be 100644
--- a/src/dotty/tools/dotc/reporting/diagnostic/Message.scala
+++ b/src/dotty/tools/dotc/reporting/diagnostic/Message.scala
@@ -3,10 +3,14 @@ package dotc
 package reporting
 package diagnostic
 
-import util.{SourcePosition, NoSourcePosition}
+import util.SourcePosition
 import core.Contexts.Context
 
 object Message {
+  /** This implicit conversion provides a fallback for error messages that have
+    * not yet been ported to the new scheme. Comment out this `implicit def` to
+    * see where old errors still exist
+    */
   implicit def toNoExplanation(str: String): Message =
     new NoExplanation(str)
 }
@@ -14,43 +18,77 @@ object Message {
 abstract class Message(val errorId: String) { self =>
   import messages._
 
+  /** The `msg` contains the diagnostic message e.g:
+    *
+    * > expected: String
+    * > found:    Int
+    *
+    * This message wil be placed underneath the position given by the enclosing
+    * `MessageContainer`
+    */
   def msg: String
+
+  /** The kind of the error message is something like "Syntax" or "Type
+    * Mismatch"
+    */
   def kind: String
+
+  /** The explanation should provide a detailed description of why the error
+    * occurred and use examples from the user's own code to illustrate how to
+    * avoid these errors.
+    */
   def explanation: String
 
+  /** It is possible to map `msg` to add details, this is at the loss of
+    * precision since the type of the resulting `Message` won't be original
+    * extending class
+    *
+    * @return a `Message` with the mapped message
+    */
   def mapMsg(f: String => String) = new Message(errorId) {
     val msg = f(self.msg)
     val kind = self.kind
     val explanation = self.explanation
   }
 
+  /** Enclose this message in an `Error` container */
   def error(pos: SourcePosition) =
     new Error(self, pos, explanation)
 
+  /** Enclose this message in an `Warning` container */
   def warning(pos: SourcePosition) =
     new Warning(self, pos, explanation)
 
+  /** Enclose this message in an `Info` container */
   def info(pos: SourcePosition) =
     new Info(self, pos, explanation)
 
+  /** Enclose this message in an `FeatureWarning` container */
   def featureWarning(pos: SourcePosition) =
     new FeatureWarning(self, pos, explanation)
 
+  /** Enclose this message in an `UncheckedWarning` container */
   def uncheckedWarning(pos: SourcePosition) =
     new UncheckedWarning(self, pos, explanation)
 
+  /** Enclose this message in an `DeprecationWarning` container */
   def deprecationWarning(pos: SourcePosition) =
     new DeprecationWarning(self, pos, explanation)
 
+  /** Enclose this message in an `MigrationWarning` container */
   def migrationWarning(pos: SourcePosition) =
     new MigrationWarning(self, pos, explanation)
 }
 
+/** The fallback `Message` containing no explanation and having no `kind` */
 class NoExplanation(val msg: String) extends Message("") {
   val explanation = ""
   val kind = ""
 }
 
+/** The extractor for `NoExplanation` can be used to check whether any error
+  * lacks an explanation
+  */
 object NoExplanation {
   def unapply(m: Message): Option[Message] =
     if (m.explanation == "") Some(m)
diff --git a/src/dotty/tools/dotc/reporting/diagnostic/messages.scala b/src/dotty/tools/dotc/reporting/diagnostic/messages.scala
index 26c5622fa..11c6b43d9 100644
--- a/src/dotty/tools/dotc/reporting/diagnostic/messages.scala
+++ b/src/dotty/tools/dotc/reporting/diagnostic/messages.scala
@@ -14,7 +14,7 @@ import printing.Formatting
 
 object messages {
 
-  /** Message container to be consumed by the reporter ---------------------- */
+  // `MessageContainer`s to be consumed by `Reporter` ---------------------- //
   class Error(
     msgFn: => Message,
     pos: SourcePosition,
@@ -73,22 +73,22 @@ object messages {
     def enablingOption(implicit ctx: Context) = ctx.settings.migration
   }
 
-  /**  Messages ----------------------------------------------------------------
-    *
+  /**  Messages
+    *  ========
     *  The role of messages is to provide the necessary details for a simple to
     *  understand diagnostic event. Each message can be turned into a message
     *  container (one of the above) by calling the appropriate method on them.
     *  For instance:
     *
     *  ```scala
-    *  EmptyCatchBlock(tree).error   // res: Error
-    *  EmptyCatchBlock(tree).warning // res: Warning
+    *  EmptyCatchBlock(tree).error(pos)   // res: Error
+    *  EmptyCatchBlock(tree).warning(pos) // res: Warning
     *  ```
     */
   import dotc.ast.Trees._
   import dotc.ast.untpd
 
-  /** Syntax Errors --------------------------------------------------------- */
+  // Syntax Errors ---------------------------------------------------------- //
   abstract class EmptyCatchOrFinallyBlock(tryBody: untpd.Tree, errNo: String)(implicit ctx: Context)
   extends Message(errNo) {
     val explanation = {
@@ -166,7 +166,7 @@ object messages {
     }
   }
 
-  /** Type Errors ----------------------------------------------------------- */
+  // Type Errors ------------------------------------------------------------ //
   case class DuplicateBind(bind: untpd.Bind, tree: untpd.CaseDef)(implicit ctx: Context)
   extends Message("E004") {
     val kind = "Naming"