From f7b8980fad5adb20e9a420a16f5b3416927dccbc Mon Sep 17 00:00:00 2001 From: Felix Mulder Date: Wed, 28 Sep 2016 11:41:36 +0200 Subject: Improve documentation for message framework --- src/dotty/tools/dotc/ast/Trees.scala | 4 +-- .../tools/dotc/reporting/diagnostic/Message.scala | 40 +++++++++++++++++++++- .../tools/dotc/reporting/diagnostic/messages.scala | 14 ++++---- 3 files changed, 48 insertions(+), 10 deletions(-) (limited to 'src') 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" -- cgit v1.2.3