Add links to Awsome Error Messages

Infrastructure to check URL exisitence in tests to keep links alive.
Link checking is switched off automatically in case github.com can't be reached.
It can be switched off via a system property as well.

Author: ennru

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

@@ -22,8 +22,17 @@ sealed trait DocumentationLink {
   def url: String
 }
 
+/** A documentation link can be rendered by tooling to direct the programmer to
+  * good resources for more details related to the compiler error or warning.
+  *
+  * To keep base links at a single place use the cases classes to share a common
+  * prefix.
+  *
+  * Links are checked for existence in tests in `dotty.tools.dotc.reporting.ErrorMessagesTests`
+  * if the error class is tested there.
+  */
 object DocumentationLink {
-  case class LanguageSpec(text: String = "Language Specification", suffix: String) extends DocumentationLink {
+  case class LanguageSpec(text: String = "Scala 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 {

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

@@ -23,7 +23,7 @@ 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 diagnostic.DocumentationLink.{DottyDocs, LanguageSpec, TourUrl}
 
 import scala.util.control.NonFatal
 
@@ -99,10 +99,13 @@ object messages {
   import ast.tpd
 
   /** Helper methods for messages */
-  def implicitClassRestrictionsText(implicit ctx: Context) =
-    hl"""|${NoColor("For a full list of restrictions on implicit classes visit")}
-         |${Blue("http://docs.scala-lang.org/overviews/core/implicit-classes.html")}"""
+  private def tryExpressionLinks = List(
+    LanguageSpec(suffix = "06-expressions.html#try-expressions")
+  )
 
+  private def implicitClassLinks = List(
+    TourUrl("More information on implicit classes", "core/implicit-classes.html")
+  )
 
   // Syntax Errors ---------------------------------------------------------- //
   abstract class EmptyCatchOrFinallyBlock(tryBody: untpd.Tree, errNo: ErrorMessageID)(implicit ctx: Context)
@@ -140,17 +143,17 @@ object messages {
            |correctly handles transfer functions like ${"return"}."""
     }
 
-    override def links: List[DocumentationLink] = List(
-      LanguageSpec(suffix = "06-expressions.html#try-expressions")
-    )
+    override def links = tryExpressionLinks
   }
 
   case class EmptyCatchBlock(tryBody: untpd.Tree)(implicit ctx: Context)
- extends EmptyCatchOrFinallyBlock(tryBody, EmptyCatchBlockID) {
+  extends EmptyCatchOrFinallyBlock(tryBody, EmptyCatchBlockID) {
     val kind = "Syntax"
     val msg =
       hl"""|The ${"catch"} block does not contain a valid expression, try
            |adding a case like - `${"case e: Exception =>"}` to the block"""
+
+    override def links = tryExpressionLinks
   }
 
   case class EmptyCatchAndFinallyBlock(tryBody: untpd.Tree)(implicit ctx: Context)
@@ -159,6 +162,8 @@ object messages {
     val msg =
       hl"""|A ${"try"} without ${"catch"} or ${"finally"} is equivalent to putting
            |its body in a block; no exceptions are handled."""
+
+    override def links = tryExpressionLinks
   }
 
   case class DeprecatedWithOperator()(implicit ctx: Context)
@@ -453,8 +458,6 @@ object messages {
            |the same name created by the compiler which would cause a naming conflict if it
            |were allowed.
            |
-           |""" + implicitClassRestrictionsText + hl"""|
-           |
            |To resolve the conflict declare ${cdef.name} inside of an ${"object"} then import the class
            |from the object at the use site if needed, for example:
            |
@@ -463,8 +466,10 @@ object messages {
            |}
            |
            |// At the use site:
-           |import Implicits.${cdef.name}"""
+           |${"import Implicits"}.${cdef.name}"""
     }
+
+    override def links = implicitClassLinks
   }
 
   case class ImplicitCaseClass(cdef: untpd.TypeDef)(implicit ctx: Context)
@@ -475,9 +480,10 @@ object messages {
     val explanation =
       hl"""|implicit classes may not be case classes. Instead use a plain class:
            |
-           |implicit class ${cdef.name}...
-           |
-           |""" + implicitClassRestrictionsText
+           |${"implicit class"} ${cdef.name}...
+           |"""
+
+    override def links = implicitClassLinks
   }
 
   case class ObjectMayNotHaveSelfType(mdef: untpd.ModuleDef)(implicit ctx: Context)
@@ -541,17 +547,19 @@ object messages {
     val kind = "Syntax"
     val msg = "error in interpolated string: identifier or block expected"
     val explanation = {
-      val code1 = "s\"$new Point(0, 0)\""
-      val code2 = "s\"${new Point(0, 0)}\""
       hl"""|This usually happens when you forget to place your expressions inside curly braces.
            |
-           |$code1
+           |${"s\"$new Point(0, 0)\""}
            |
            |should be written as
            |
-           |$code2
+           |${"s\"${new Point(0, 0)}\""}
            |"""
     }
+
+    override def links = List(
+      TourUrl("More on String Interpolation", "core/string-interpolation.html")
+    )
   }
 
   case class UnboundPlaceholderParameter()(implicit ctx:Context)
@@ -1715,19 +1723,13 @@ object messages {
     val kind = "Syntax"
     val msg = s"modifier(s) `$flags' not allowed for ${printableType.getOrElse("combination")}"
     val explanation = {
-      val first = "sealed def y: Int = 1"
-      val second = "sealed lazy class z"
       hl"""You tried to use a modifier that is inapplicable for the type of item under modification
-         |
-         |  Please see the official Scala Language Specification section on modifiers:
-         |  https://www.scala-lang.org/files/archive/spec/2.11/05-classes-and-objects.html#modifiers
          |
          |Consider the following example:
-         |$first
+         |${"sealed def y: Int = 1"}
          |In this instance, the modifier 'sealed' is not applicable to the item type 'def' (method)
-         |$second
-         |In this instance, the modifier combination is not supported
-        """
+         |${"sealed lazy class z"}
+         |In this instance, the modifier combination is not supported"""
     }
 
     override def links: List[DocumentationLink] = List(

compiler/test/dotty/tools/dotc/reporting/ErrorMessagesTest.scala

@@ -44,9 +44,4 @@ trait ErrorMessagesTest extends DottyTest {
     }
   }
 
-  def assertMessageCount(expected: Int, messages: List[Message]): Unit =
-    assertEquals(messages.mkString,
-      expected,
-      messages.length
-    )
 }