Add links to Awsome Error Messages

Error messages should support including links for further reading that can be
picked up by tools like IDEs.
Examples are links to the language specification, or the "changes in Dotty" pages.

Author: ennru

compiler/src/dotty/tools/dotc/reporting/ConsoleReporter.scala

@@ -34,8 +34,10 @@ class ConsoleReporter(
         true
     }
 
-    if (didPrint && ctx.shouldExplain(m))
+    if (didPrint && ctx.shouldExplain(m)) {
       printMessage(explanation(m.contained()))
+      if (m.contained().links.nonEmpty) printMessage(documentationLinks(m.contained()))
+    }
     else if (didPrint && m.contained().explanation.nonEmpty)
       printMessage("\nlonger explanation available when compiling with `-explain`")
   }

compiler/src/dotty/tools/dotc/reporting/MessageRendering.scala

@@ -4,14 +4,14 @@ package reporting
 
 import core.Contexts.Context
 import core.Decorators._
-import printing.Highlighting.{Blue, Red}
+import printing.Highlighting.{Blue, Red, Yellow}
 import printing.SyntaxHighlighting
 import diagnostic.{ErrorMessageID, Message, MessageContainer, NoExplanation}
 import diagnostic.messages._
 import util.SourcePosition
-import util.Chars.{ LF, CR, FF, SU }
-import scala.annotation.switch
+import util.Chars.{CR, FF, LF, SU}
 
+import scala.annotation.switch
 import scala.collection.mutable
 
 trait MessageRendering {
@@ -130,13 +130,29 @@ trait MessageRendering {
     val sb = new StringBuilder(
       hl"""|
            |${Blue("Explanation")}
-           |${Blue("===========")}"""
+           |${Blue("===========")}
+           |"""
     )
-    sb.append('\n').append(m.explanation)
-    if (m.explanation.lastOption != Some('\n')) sb.append('\n')
+    sb.append(m.explanation)
+    if (!m.explanation.endsWith("\n")) sb.append('\n')
     sb.toString
   }
 
+  /** Documentation links rendered under "Further reading" header */
+  def documentationLinks(m: Message)(implicit ctx: Context): String = {
+    val sb = new StringBuilder(
+      hl"""|
+           |${Blue("Further reading")}
+           |${Blue("===============")}
+           |"""
+    )
+    for (link <- m.links) {
+      sb.append(link.text).append(hl" ${Yellow(link.url)}\n")
+    }
+    sb.append('\n').toString
+  }
+
+
   /** The whole message rendered from `msg` */
   def messageAndPos(msg: Message, pos: SourcePosition, diagnosticLevel: String)(implicit ctx: Context): String = {
     val sb = mutable.StringBuilder.newBuilder

compiler/src/dotty/tools/dotc/reporting/diagnostic/Message.scala

@@ -17,6 +17,24 @@ object Message {
     new NoExplanation(str)
 }
 
+sealed trait DocumentationLink {
+  def text: String
+  def url: String
+}
+
+object DocumentationLink {
+  case class LanguageSpec(text: String = "Language Specification", suffix: String) extends DocumentationLink {
+    val url = s"https://www.scala-lang.org/files/archive/spec/2.13/$suffix"
+  }
+  case class TourUrl(text: String, suffix: String) extends DocumentationLink {
+    val url = s"http://docs.scala-lang.org/overviews/$suffix"
+  }
+  case class DottyDocs(text: String = "Dotty documentation", suffix: String) extends DocumentationLink {
+    val url = s"http://dotty.epfl.ch/docs/$suffix"
+  }
+  case class FullUrl(text: String, url: String) extends DocumentationLink
+}
+
 /** A `Message` contains all semantic information necessary to easily
   * comprehend what caused the message to be logged. Each message can be turned
   * into a `MessageContainer` which contains the log level and can later be
@@ -56,6 +74,8 @@ abstract class Message(val errorId: ErrorMessageID) { self =>
     */
   def explanation: String
 
+  def links: List[DocumentationLink] = Nil
+
   /** The implicit `Context` in messages is a large thing that we don't want
     * persisted. This method gets around that by duplicating the message
     * without the implicit context being passed along.
@@ -64,6 +84,8 @@ abstract class Message(val errorId: ErrorMessageID) { self =>
     val msg         = self.msg
     val kind        = self.kind
     val explanation = self.explanation
+    private val persistedLinks = self.links
+    override def links = persistedLinks
   }
 }
 

compiler/src/dotty/tools/dotc/reporting/diagnostic/MessageContainer.scala

@@ -15,10 +15,7 @@ object MessageContainer {
   implicit class MessageContext(val c: Context) extends AnyVal {
     def shouldExplain(cont: MessageContainer): Boolean = {
       implicit val ctx = c
-      cont.contained().explanation match {
-        case "" => false
-        case _ => ctx.settings.explain.value
-      }
+      cont.contained().explanation.nonEmpty && c.settings.explain.value
     }
   }
 }

compiler/src/dotty/tools/dotc/reporting/diagnostic/messages.scala

@@ -23,6 +23,8 @@ import dotty.tools.dotc.ast.Trees
 import dotty.tools.dotc.ast.untpd.Modifiers
 import dotty.tools.dotc.core.Flags.{FlagSet, Mutable}
 import dotty.tools.dotc.core.SymDenotations.SymDenotation
+import dotty.tools.dotc.reporting.diagnostic.DocumentationLink.{DottyDocs, LanguageSpec}
+
 import scala.util.control.NonFatal
 
 object messages {
@@ -137,6 +139,10 @@ object messages {
            |It is recommended to use the ${"NonFatal"} extractor to catch all exceptions as it
            |correctly handles transfer functions like ${"return"}."""
     }
+
+    override def links: List[DocumentationLink] = List(
+      LanguageSpec(suffix = "06-expressions.html#try-expressions")
+    )
   }
 
   case class EmptyCatchBlock(tryBody: untpd.Tree)(implicit ctx: Context)
@@ -164,6 +170,10 @@ object messages {
       hl"""|Dotty introduces intersection types - `&' types. These replace the
            |use of the ${"with"} keyword. There are a few differences in
            |semantics between intersection types and using `${"with"}'."""
+
+    override def links = List(
+      DottyDocs(suffix = "reference/intersection-types.html")
+    )
   }
 
   case class CaseClassMissingParamList(cdef: untpd.TypeDef)(implicit ctx: Context)
@@ -176,6 +186,10 @@ object messages {
       hl"""|${cdef.name} must have at least one parameter list, if you would rather
            |have a singleton representation of ${cdef.name}, use a "${"case object"}".
            |Or, add an explicit `()' as a parameter list to ${cdef.name}."""
+
+    override def links = List(
+      LanguageSpec(suffix = "05-classes-and-objects.html#case-classes")
+    )
   }
 
   case class AnonymousFunctionMissingParamType(param: untpd.ValDef,
@@ -204,6 +218,10 @@ object messages {
            |Make sure you give it a type of what you expect to match and help the type inference system:
            |
            |${"val f: Seq[Int] => Option[List[Int]] = { case xs @ List(1, 2, 3) => Some(xs) }"} """
+
+    override def links = List(
+      LanguageSpec(suffix = "06-expressions.html#anonymous-functions")
+    )
   }
 
   case class WildcardOnTypeArgumentNotAllowedOnNew()(implicit ctx: Context)
@@ -410,7 +428,12 @@ object messages {
            |
            |$code2
            |"""
+
     }
+
+    override def links = List(
+      DottyDocs(suffix = "reference/trait-parameters.html")
+    )
   }
 
   case class TopLevelImplicitClass(cdef: untpd.TypeDef)(implicit ctx: Context)
@@ -1694,6 +1717,10 @@ object messages {
          |In this instance, the modifier combination is not supported
         """
     }
+
+    override def links: List[DocumentationLink] = List(
+      LanguageSpec("Please see the official Scala Language Specification section on modifiers",
+        "05-classes-and-objects.html#modifiers"))
   }
 
   case class ImplicitFunctionTypeNeedsNonEmptyParameterList()(implicit ctx: Context)

sbt-bridge/src/xsbt/DelegatingReporter.scala

@@ -47,8 +47,9 @@ final class DelegatingReporter(delegate: xsbti.Reporter) extends Reporter
 
     val sb = new StringBuilder()
     sb.append(messageAndPos(cont.contained(), cont.pos, diagnosticLevel(cont)))
-    if (ctx.shouldExplain(cont) && cont.contained().explanation.nonEmpty) {
+    if (ctx.shouldExplain(cont)) {
       sb.append(explanation(cont.contained()))
+      if (cont.contained().links.nonEmpty) sb.append(documentationLinks(cont.contained()))
     }
 
     delegate.log(position, sb.toString(), severity)