Fix existing and document remaining error codes

Author: WojciechMazur

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

@@ -2,7 +2,6 @@
 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.
@@ -37,8 +36,8 @@ correctly handles transfer functions like `return`.
 
 ## Example
 
-```scala sc:fail
-@main def test() =
+```scala sc:fail sc-opts:-explain
+def example() =
   try {
     println("hello")
   } catch { }
@@ -47,37 +46,61 @@ correctly handles transfer functions like `return`.
 ### Error
 
 ```scala sc:nocompile
--- [E001] Syntax Error: example.scala:4:4 
+-- [E001] Syntax Error: example.scala:4:4 --------------------------------------
 4 |  } 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 
+### Solution
 
-```scala sc:compile 
+```scala sc:compile
 // Remove redundant 'try' block
-println("hello")
-``` 
+def example() =
+  println("hello")
+```
 
-```scala sc:compile 
+```scala sc:compile
 // Alternative: Add a case handler to catch exceptions
 import scala.util.control.NonFatal
 
-try {
-  println("hello")
-} catch {
-  case NonFatal(e) => println(s"Caught: $e")
-}
-``` 
+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
-try {
-  println("hello")
-} finally {
-  println("cleanup")
-}
+def example() =
+  try println("hello")
+  finally println("cleanup")
 ```
 

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

@@ -2,7 +2,6 @@
 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.
@@ -37,8 +36,8 @@ correctly handles transfer functions like `return`.
 
 ## Example
 
-```scala sc:fail sc-opts:-Werror
-@main def test() =
+```scala sc:fail sc-opts:-explain,-Werror
+@main def example() =
   try {
     println("hello")
   }
@@ -47,39 +46,67 @@ correctly handles transfer functions like `return`.
 ### Warning
 
 ```scala sc:nocompile
--- [E002] Syntax Warning: example.scala:2:2 
+-- [E002] Syntax Warning: example.scala:2:2 ------------------------------------
 2 |  try {
   |  ^
   |  A try without catch or finally is equivalent to putting
   |  its body in a block; no exceptions are handled.
 3 |    println("hello")
 4 |  }
+  |-----------------------------------------------------------------------------
+  | 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 
+### Solution
 
 ```scala sc:compile sc-opts:-Werror
 // Remove redundant 'try' block
-println("hello")
-``` 
+def example() = 
+  println("hello")
+```
 
 ```scala sc:compile sc-opts:-Werror
 // Alternative: Add a catch block to handle exceptions
 import scala.util.control.NonFatal
 
-try {
-  println("hello")
-} catch {
-  case NonFatal(e) => println(s"Caught: $e")
-}
-``` 
+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
-try {
-  println("hello")
-} finally {
-  println("cleanup")
-}
+def example() = 
+  try 
+    println("hello")
+  finally 
+    println("cleanup")
 ```
 

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

@@ -2,7 +2,6 @@
 title: E003: Deprecated With Operator
 kind: Warning
 ---
-
 # E003: Deprecated With Operator
 
 This warning is emitted when using `with` as a type operator to create compound types. In Scala 3, `with` has been deprecated in favor of intersection types using `&`.
@@ -15,7 +14,7 @@ semantics between intersection types and using `with`.
 
 ## Example
 
-```scala sc:fail sc-opts:-Werror
+```scala sc:fail sc-opts:-explain,-Werror
 trait A
 trait B
 def test(x: A with B): Unit = ()
@@ -24,21 +23,28 @@ def test(x: A with B): Unit = ()
 ### Warning
 
 ```scala sc:nocompile
--- [E003] Syntax Warning: example.scala:3:14 
+-- [E003] Syntax Warning: example.scala:3:14 -----------------------------------
 3 |def test(x: A with B): Unit = ()
   |              ^^^^
   |with as a type operator has been deprecated; use & instead
   |This construct can be rewritten automatically under -rewrite -source 3.4-migration.
+  |-----------------------------------------------------------------------------
+  | Explanation (enabled by `-explain`)
+  |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+  | 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.
+   -----------------------------------------------------------------------------
 ```
 
-### Solution 
+### Solution
 
 ```scala sc:compile sc-opts:-Werror
 // Use intersection type operator & instead of with
 trait A
 trait B
 def test(x: A & B): Unit = ()
-``` 
+```
 
 ```scala sc:compile sc-opts:-Werror
 // The change also applies to type aliases and class definitions

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

@@ -2,7 +2,6 @@
 title: E004: Case Class Missing Param List
 kind: Error
 ---
-
 # E004: Case Class Missing Param List
 
 This error is emitted when a `case class` is defined without any parameter list. In Scala 3, case classes must have at least one parameter list.
@@ -15,32 +14,39 @@ Or, add an explicit `()` as a parameter list to `Empty`.
 
 ## Example
 
-```scala sc:fail
+```scala sc:fail sc-opts:-explain
 case class Empty
 ```
 
 ### Error
 
 ```scala sc:nocompile
--- [E004] Syntax Error: example.scala:1:11 
+-- [E004] Syntax Error: example.scala:1:11 -------------------------------------
 1 |case class Empty
   |           ^^^^^
   |           A case class must have at least one parameter list
+  |-----------------------------------------------------------------------------
+  | Explanation (enabled by `-explain`)
+  |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+  | Empty must have at least one parameter list, if you would rather
+  | have a singleton representation of Empty, use a "case object".
+  | Or, add an explicit () as a parameter list to Empty.
+   -----------------------------------------------------------------------------
 ```
 
-### Solution 
+### Solution
 
-```scala sc:compile 
+```scala sc:compile
 // Use case object for singleton representation
 case object Empty
-``` 
+```
 
-```scala sc:compile 
+```scala sc:compile
 // Add an explicit empty parameter list
 case class Empty()
-``` 
+```
 
-```scala sc:compile 
+```scala sc:compile
 // Or define actual parameters
 case class Empty(value: String)
 ```

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

@@ -2,7 +2,6 @@
 title: E005: Duplicate Bind
 kind: Error
 ---
-
 # E005: Duplicate Bind
 
 This error is emitted when the same variable name is used more than once in a pattern match case. Each bound variable in a `case` pattern must have a unique name.
@@ -19,35 +18,46 @@ case (a, a) => a
 
 ## Example
 
-```scala sc:fail
+```scala sc:fail sc-opts:-explain
 def test(x: Any) = x match
   case (a, a) => a
 ```
 
 ### Error
 
 ```scala sc:nocompile
--- [E005] Naming Error: example.scala:2:11 
+-- [E005] Naming Error: example.scala:2:11 -------------------------------------
 2 |  case (a, a) => a
   |           ^
   |           duplicate pattern variable: a
+  |-----------------------------------------------------------------------------
+  | Explanation (enabled by `-explain`)
+  |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+  | For each case bound variable names have to be unique. In:
+  |
+  | case (a, a) =>  {
+  |   a
+  | }
+  |
+  | a is not unique. Rename one of the bound variables!
+   -----------------------------------------------------------------------------
 ```
 
-### Solution 
+### Solution
 
-```scala sc:compile 
+```scala sc:compile
 // Use unique names for each bound variable
 def test(x: Any) = x match
   case (a, b) => (a, b)
-``` 
+```
 
-```scala sc:compile 
+```scala sc:compile
 // Use wildcard _ if you don't need the value
 def test(x: Any) = x match
   case (a, _) => a
-``` 
+```
 
-```scala sc:compile 
+```scala sc:compile
 // Use a guard if you want to match equal values
 def test(x: Any) = x match
   case (a, b) if a == b => a