Document Scala compiler error codes

.github/workflows/scaladoc.yaml

@@ -85,3 +85,41 @@ jobs:
 
       - name: Test sourcelinks to stdlib
         run: true # ./project/scripts/sbt scaladoc/sourceLinksIntegrationTest:test
+
+  check-error-code-snippets:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: coursier/cache-action@v7
+      - uses: VirtusLab/scala-cli-setup@v1
+        with: 
+          jvm: temurin:17
+          apps: sbt
+      - name: Publish compiler locally
+        run: |
+          version=$(./project/scripts/sbt "print scala3-compiler-bootstrapped-new/version" | tail -n1)
+          echo "SCALA_VERSION=$version" >> $GITHUB_ENV
+          echo "Would test snippets using Scala $version"
+
+          # Publish locally minimal set of artifacts that would be required to test snippets 
+          sbt "set every doc := new File(\"unused\");\
+               scala3-bootstrapped-new/publishLocal
+              "
+      - name: Test error code snippets
+        shell: bash
+        run: scala-cli test -S ${{ env.SCALA_VERSION }} --with-compiler project/scripts/checkErrorCodeSnippets.test.scala -- +l +a +c
+      - name: "[On failure] Print reproduction/fix steps"
+        if: failure()
+        run: |
+          cat << EOF >> $GITHUB_STEP_SUMMARY
+          Snippets validation for error codes failed
+
+          If you've modified messages of positions of error codes, you might need to update the expected outputs, to do it run: following command:
+          scala -S ${{ env.SCALA_VERSION }} project/scripts/checkErrorCodeSnippets.scala --with-compiler --main-class=updateAllErrorCodeOutputs
+
+          Single error code validation can be performed using:
+          scala -S ${{ env.SCALA_VERSION }} project/scripts/checkErrorCodeSnippets.scala --with-compiler -- docs/_docs/reference/error-codes/E001.md [--verbose --update-output]
+
+          To check the validation use dedicated test suite:
+          scala test -S ${{ env.SCALA_VERSION }} --with-compiler project/scripts/checkErrorCodeSnippets.test.scala -- +l +a +c
+          EOF

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

@@ -3,6 +3,8 @@ package dotty.tools.dotc.reporting
 //////////////////////////////////////////////////////////////////////////
 // IMPORTANT                                                            //
 // Only add new IDs at end of the enumeration list and never remove IDs //
+// When adding a new ID, also update the reference documentation at     //
+// docs/_docs/reference/error-codes/                                    //
 //////////////////////////////////////////////////////////////////////////
 
 /** Unique IDs identifying the messages, this will be used to reference documentation online.
@@ -98,7 +100,7 @@ enum ErrorMessageID(val isActive: Boolean = true) extends java.lang.Enum[ErrorMe
   case SuperCallsNotAllowedInlineableID // errorNumber: 82
   case NotAPathID // errorNumber: 83
   case WildcardOnTypeArgumentNotAllowedOnNewID // errorNumber: 84
-  case FunctionTypeNeedsNonEmptyParameterListID // errorNumber: 85
+  case FunctionTypeNeedsNonEmptyParameterListID extends ErrorMessageID(isActive = false) // errorNumber: 85
   case WrongNumberOfParametersID // errorNumber: 86
   case DuplicatePrivateProtectedQualifierID // errorNumber: 87
   case ExpectedStartOfTopLevelDefinitionID // errorNumber: 88
@@ -107,7 +109,7 @@ enum ErrorMessageID(val isActive: Boolean = true) extends java.lang.Enum[ErrorMe
   case ReturnOutsideMethodDefinitionID // errorNumber: 91
   case UncheckedTypePatternID // errorNumber: 92
   case ExtendFinalClassID // errorNumber: 93
-  case EnumCaseDefinitionInNonEnumOwnerID // errorNumber: 94
+  case EnumCaseDefinitionInNonEnumOwnerID extends ErrorMessageID(isActive = false) // errorNumber: 94
   case ExpectedTypeBoundOrEqualsID // errorNumber: 95
   case ClassAndCompanionNameClashID // errorNumber: 96
   case TailrecNotApplicableID // errorNumber: 97
@@ -116,9 +118,9 @@ enum ErrorMessageID(val isActive: Boolean = true) extends java.lang.Enum[ErrorMe
   case MissingEmptyArgumentListID // errorNumber: 100
   case DuplicateNamedTypeParameterID // errorNumber: 101
   case UndefinedNamedTypeParameterID // errorNumber: 102
-  case IllegalStartOfStatementID // errorNumber: 1033
+  case IllegalStartOfStatementID // errorNumber: 103
   case TraitIsExpectedID // errorNumber: 104
-  case TraitRedefinedFinalMethodFromAnyRefID // errorNumber: 105
+  case TraitRedefinedFinalMethodFromAnyRefID extends ErrorMessageID(isActive = false) // errorNumber: 105
   case PackageNameAlreadyDefinedID // errorNumber: 106
   case UnapplyInvalidNumberOfArgumentsID // errorNumber: 107
   case UnapplyInvalidReturnTypeID // errorNumber: 108
@@ -163,9 +165,9 @@ enum ErrorMessageID(val isActive: Boolean = true) extends java.lang.Enum[ErrorMe
   case RedundantModifierID // errorNumber: 147
   case TypedCaseDoesNotExplicitlyExtendTypedEnumID // errorNumber: 148
   case IllegalRedefinitionOfStandardKindID // errorNumber: 149
-  case NoExtensionMethodAllowedID // errorNumber: 150
-  case ExtensionMethodCannotHaveTypeParamsID // errorNumber: 151
-  case ExtensionCanOnlyHaveDefsID // errorNumber: 152
+  case NoExtensionMethodAllowedID extends ErrorMessageID(isActive = false) // errorNumber: 150
+  case ExtensionMethodCannotHaveTypeParamsID extends ErrorMessageID(isActive = false) // errorNumber: 151
+  case ExtensionCanOnlyHaveDefsID extends ErrorMessageID(isActive = false) // errorNumber: 152
   case UnexpectedPatternForSummonFromID // errorNumber: 153
   case AnonymousInstanceCannotBeEmptyID // errorNumber: 154
   case TypeSpliceInValPatternID extends ErrorMessageID(isActive = false) // errorNumber: 155
@@ -209,7 +211,7 @@ enum ErrorMessageID(val isActive: Boolean = true) extends java.lang.Enum[ErrorMe
   case VolatileOnValID // errorNumber: 193
   case ExtensionNullifiedByMemberID // errorNumber: 194
   case PhantomSymbolNotValueID // errorNumber: 195
-  case ContextBoundCompanionNotValueID // errorNumber: 196
+  case ContextBoundCompanionNotValueID extends ErrorMessageID(isActive = false) // errorNumber: 196
   case InlinedAnonClassWarningID // errorNumber: 197
   case UnusedSymbolID // errorNumber: 198
   case TailrecNestedCallID //errorNumber: 199

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

@@ -2108,11 +2108,6 @@ class TraitIsExpected(symbol: Symbol)(using Context) extends SyntaxMsg(TraitIsEx
   }
 }
 
-class TraitRedefinedFinalMethodFromAnyRef(method: Symbol)(using Context) extends SyntaxMsg(TraitRedefinedFinalMethodFromAnyRefID) {
-  def msg(using Context) = i"Traits cannot redefine final $method from ${hl("class AnyRef")}."
-  def explain(using Context) = ""
-}
-
 class AlreadyDefined(name: Name, owner: Symbol, conflicting: Symbol)(using Context)
 extends NamingMsg(AlreadyDefinedID):
   def msg(using Context) =
@@ -2823,29 +2818,6 @@ class IllegalRedefinitionOfStandardKind(kindType: String, name: Name)(using Cont
         | Please choose a different name to avoid conflicts
         |"""
 }
-
-class NoExtensionMethodAllowed(mdef: untpd.DefDef)(using Context)
-  extends SyntaxMsg(NoExtensionMethodAllowedID) {
-  def msg(using Context) = i"No extension method allowed here, since collective parameters are given"
-  def explain(using Context) =
-    i"""|Extension method:
-        |  `${mdef}`
-        |is defined inside an extension clause which has collective parameters.
-        |"""
-}
-
-class ExtensionMethodCannotHaveTypeParams(mdef: untpd.DefDef)(using Context)
-  extends SyntaxMsg(ExtensionMethodCannotHaveTypeParamsID) {
-  def msg(using Context) = i"Extension method cannot have type parameters since some were already given previously"
-
-  def explain(using Context) =
-    i"""|Extension method:
-        |  `${mdef}`
-        |has type parameters `[${mdef.leadingTypeParams.map(_.show).mkString(",")}]`, while the extension clause has
-        |it's own type parameters. Please consider moving these to the extension clause's type parameter list.
-        |"""
-}
-
 class ExtensionCanOnlyHaveDefs(mdef: untpd.Tree)(using Context)
   extends SyntaxMsg(ExtensionCanOnlyHaveDefsID) {
   def msg(using Context) = i"Only methods allowed here, since collective parameters are given"

docs/_docs/reference/error-codes/E001.md

@@ -0,0 +1,99 @@
+---
+title: E001: Empty Catch Block
+kind: Error
+---
+# E001: Empty Catch Block
+
+This error is emitted when a `try` expression has a `catch` block that does not contain any case handlers.
+
+A `try` expression should be followed by some mechanism to handle any exceptions
+thrown. Typically a `catch` expression follows the `try` and pattern matches
+on any expected exceptions. For example:
+
+```scala
+try
+  println("hello")
+catch
+  case e: Exception => ???
+```
+
+It is also possible to follow a `try` immediately by a `finally` - letting the
+exception propagate - but still allowing for some clean up in `finally`:
+
+```scala
+try
+  println("hello")
+finally
+  // perform your cleanup here!
+```
+
+It is recommended to use the `NonFatal` extractor to catch all exceptions as it
+correctly handles transfer functions like `return`.
+
+---
+
+## Example
+
+```scala sc:fail sc-opts:-explain
+def example() =
+  try println("hello")
+  catch { }
+```
+
+### Error
+
+```scala sc:nocompile
+-- [E001] Syntax Error: example.scala:3:2 --------------------------------------
+3 |  catch { }
+  |  ^^^^^^^^^
+  |  The catch block does not contain a valid expression, try
+  |  adding a case like - case e: Exception => to the block
+  |-----------------------------------------------------------------------------
+  | Explanation (enabled by `-explain`)
+  |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+  | A try expression should be followed by some mechanism to handle any exceptions
+  | thrown. Typically a catch expression follows the try and pattern matches
+  | on any expected exceptions. For example:
+  |
+  | import scala.util.control.NonFatal
+  |
+  | try println("hello") catch {
+  |   case NonFatal(e) => ???
+  | }
+  |
+  | It is also possible to follow a try immediately by a finally - letting the
+  | exception propagate - but still allowing for some clean up in finally:
+  |
+  | try println("hello") finally {
+  |   // perform your cleanup here!
+  | }
+  |
+  | It is recommended to use the NonFatal extractor to catch all exceptions as it
+  | correctly handles transfer functions like return.
+   -----------------------------------------------------------------------------
+```
+
+### Solution
+
+```scala sc:compile
+// Remove redundant 'try' block
+def example() =
+  println("hello")
+```
+
+```scala sc:compile
+// Alternative: Add a case handler to catch exceptions
+import scala.util.control.NonFatal
+
+def example() =
+  try println("hello")
+  catch { case NonFatal(e) => println(s"Caught: $e") }
+```
+
+```scala sc:compile
+// Alternative: use finally instead if you only need cleanup
+def example() =
+  try println("hello")
+  finally println("cleanup")
+```
+

docs/_docs/reference/error-codes/E002.md

@@ -0,0 +1,102 @@
+---
+title: E002: Empty Catch And Finally Block
+kind: Warning
+---
+# E002: Empty Catch And Finally Block
+
+This warning is emitted when a `try` expression has neither a `catch` block nor a `finally` block. Such a `try` is redundant since no exceptions are handled.
+
+A `try` expression should be followed by some mechanism to handle any exceptions
+thrown. Typically a `catch` expression follows the `try` and pattern matches
+on any expected exceptions. For example:
+
+```scala
+try
+  println("hello")
+catch
+  case e: Exception => ???
+```
+
+It is also possible to follow a `try` immediately by a `finally` - letting the
+exception propagate - but still allowing for some clean up in `finally`:
+
+```scala
+try
+  println("hello")
+finally
+  // perform your cleanup here!
+```
+
+It is recommended to use the `NonFatal` extractor to catch all exceptions as it
+correctly handles transfer functions like `return`.
+
+---
+
+## Example
+
+```scala sc:fail sc-opts:-explain,-Werror
+@main def example() =
+  try println("hello")
+```
+
+### Warning
+
+```scala sc:nocompile
+-- [E002] Syntax Warning: example.scala:2:2 ------------------------------------
+2 |  try println("hello")
+  |  ^^^^^^^^^^^^^^^^^^^^
+  |  A try without catch or finally is equivalent to putting
+  |  its body in a block; no exceptions are handled.
+  |-----------------------------------------------------------------------------
+  | Explanation (enabled by `-explain`)
+  |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+  | A try expression should be followed by some mechanism to handle any exceptions
+  | thrown. Typically a catch expression follows the try and pattern matches
+  | on any expected exceptions. For example:
+  |
+  | import scala.util.control.NonFatal
+  |
+  | try println("hello") catch {
+  |   case NonFatal(e) => ???
+  | }
+  |
+  | It is also possible to follow a try immediately by a finally - letting the
+  | exception propagate - but still allowing for some clean up in finally:
+  |
+  | try println("hello") finally {
+  |   // perform your cleanup here!
+  | }
+  |
+  | It is recommended to use the NonFatal extractor to catch all exceptions as it
+  | correctly handles transfer functions like return.
+   -----------------------------------------------------------------------------
+```
+
+### Solution
+
+```scala sc:compile sc-opts:-Werror
+// Remove redundant 'try' block
+def example() =
+  println("hello")
+```
+
+```scala sc:compile sc-opts:-Werror
+// Alternative: Add a catch block to handle exceptions
+import scala.util.control.NonFatal
+
+def example() =
+  try
+    println("hello")
+  catch
+    case NonFatal(e) => println(s"Caught: $e")
+```
+
+```scala sc:compile sc-opts:-Werror
+// Alternative: Add a finally block for cleanup
+def example() =
+  try
+    println("hello")
+  finally
+    println("cleanup")
+```
+