Add support for snippet importing. Refactor docs to use new feature.

Author: pikinier20

docs/docs/reference/other-new-features/creator-applications.md

@@ -9,22 +9,20 @@ function application, without needing to write `new`.
 
 Scala 3 generalizes this scheme to all concrete classes. Example:
 
-```scala
+```scala sc-id:1
 class MyStringBuilder(s: String):
   def this() = this("")
+```
 
+```scala sc-compile-with:1
 MyStringBuilder("abc")  // old: new MyStringBuilder("abc")
 MyStringBuilder()       // old: new MyStringBuilder()
 ```
 
 This works since a companion object with two `apply` methods
 is generated together with the class. The object looks like this:
 
-```scala
-//{
-class MyStringBuilder(s: String):
-  def this() = this("")
-//}
+```scala sc-compile-with:1
 object MyStringBuilder:
   inline def apply(s: String): MyStringBuilder = new MyStringBuilder(s)
   inline def apply(): MyStringBuilder = new MyStringBuilder()

docs/docs/reference/other-new-features/explicit-nulls.md

@@ -148,20 +148,16 @@ We illustrate the rules with following examples:
 
   ==>
 
-  ```scala
+  ```scala sc-id:1
   class C[T] { def foo(): T | Null = null }
   ```
 
   Notice this is rule is sometimes too conservative, as witnessed by
 
-  ```scala sc:fail
-  //{
-  class C[T] { def foo(): T | Null = null }
-  type Bool
-  //}
+  ```scala sc:fail sc-compile-with:1
   class InScala:
-    val c: C[Bool] = ???  // C as above
-    val b: Bool = c.foo() // no longer typechecks, since foo now returns Bool | Null
+    val c: C[Boolean] = ???  // C as above
+    val b: Boolean = c.foo() // no longer typechecks, since foo now returns Bool | Null
   ```
 
 - We can reduce the number of redundant nullable types we need to add. Consider
@@ -173,8 +169,11 @@ We illustrate the rules with following examples:
 
   ==>
 
-  ```scala
+  ```scala sc-id:2
   abstract class Box[T] { def get(): T | Null }
+  ```
+
+  ```scala sc-compile-with:2
   abstract class BoxFactory[T] { def makeBox(): Box[T] | Null }
   ```
 
@@ -199,10 +198,7 @@ We illustrate the rules with following examples:
 
   ==>
 
-  ```scala
-  //{
-  abstract class Box[T] { def get(): T | Null }
-  //}
+  ```scala sc-compile-with:2
   abstract class BoxFactory[T]:
     def makeBox(): Box[T | Null] | Null
     def makeCrazyBoxes(): java.util.List[Box[java.util.List[T] | Null]] | Null
@@ -232,7 +228,7 @@ We illustrate the rules with following examples:
 
   ```scala
   //{
-  def getNewName(): String | Null = ???
+  def getNewName(): String = ???
   //}
   class Constants:
     val NAME: String = "name"
@@ -255,10 +251,7 @@ We illustrate the rules with following examples:
 
   ==>
 
-  ```scala
-  //{
-  abstract class Box[T] { def get(): T | Null }
-  //}
+  ```scala sc-compile-with:2
   abstract class C:
     val name: String
     def getNames(prefix: String | Null): java.util.List[String] // we still need to nullify the paramter types

docs/docs/reference/other-new-features/export.md

@@ -6,7 +6,7 @@ movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/export.
 
 An export clause defines aliases for selected members of an object. Example:
 
-```scala
+```scala sc-name:Model.scala
 class BitMap
 class InkJet
 
@@ -39,29 +39,7 @@ final type PrinterType              = printUnit.PrinterType
 
 They can be accessed inside `Copier` as well as from outside:
 
-```scala
-//{
-class BitMap
-class InkJet
-
-class Printer:
-  type PrinterType
-  def print(bits: BitMap): Unit = ???
-  def status: List[String] = ???
-
-class Scanner:
-  def scan(): BitMap = ???
-  def status: List[String] = ???
-
-class Copier:
-  private val printUnit = new Printer { type PrinterType = InkJet }
-  private val scanUnit = new Scanner
-
-  export scanUnit.scan
-  export printUnit.{status => _, *}
-
-  def status: List[String] = printUnit.status ++ scanUnit.status
-//}
+```scala sc-compile-with:Model.scala
 val copier = new Copier
 copier.print(copier.scan())
 ```
@@ -164,20 +142,19 @@ ImportSelectors   ::=  NamedSelector [‘,’ ImportSelectors]
 Export clauses raise questions about the order of elaboration during type checking.
 Consider the following example:
 
-```scala
+```scala sc-id:1
 class B { val c: Int = ??? }
 object a { val b = new B }
+```
+
+```scala sc-compile-with:1
 export a.*
 export b.*
 ```
 
 Is the `export b.*` clause legal? If yes, what does it export? Is it equivalent to `export a.b.*`? What about if we swap the last two clauses?
 
-```scala sc:fail
-//{
-class B { val c: Int = ??? }
-object a { val b = new B }
-//}
+```scala sc:fail sc-compile-with:1
 export b.*
 export a.*
 ```

docs/docs/reference/other-new-features/indentation-experimental.md

@@ -92,16 +92,14 @@ IndentedArgument ::=  indent (CaseClauses | Block) outdent
 Note that a lambda argument must have the `=>` at the end of a line for braces
 to be optional. For instance, the following would also be incorrect:
 
-```scala sc:fail
-  //{
-  val xs: Seq[Int]
-  //}
+```scala sc-id:1
+val xs: Seq[Int]
+```
+
+```scala sc:fail sc-compile-with:1
   xs.map x => x + 1   // error: braces or parentheses are required
 ```
 The lambda has to be enclosed in braces or parentheses:
-```scala
-  //{
-  val xs: Seq[Int]
-  //}
+```scala sc-compile-with:1
   xs.map(x => x + 1)  // ok
 ```

docs/docs/reference/other-new-features/matchable.md

@@ -120,7 +120,7 @@ is guaranteed to succeed at run-time since `Any` and `Matchable` both erase to
 
 For instance, consider the definitions
 
-```scala
+```scala sc-id:1
 opaque type Meter = Double
 def Meter(x: Double) = x
 
@@ -130,27 +130,13 @@ def Second(x: Double) = x
 
 Here, universal `equals` will return true for
 
-```scala
-//{
-opaque type Meter = Double
-def Meter(x: Double) = x
-
-opaque type Second = Double
-def Second(x: Double) = x
-//}
+```scala sc-compile-with:1
 Meter(10).equals(Second(10))
 ```
 
 even though this is clearly false mathematically. With [multiversal equality](../contextual/multiversal-equality.md) one can mitigate that problem somewhat by turning
 
-```scala
-//{
-opaque type Meter = Double
-def Meter(x: Double) = x
-
-opaque type Second = Double
-def Second(x: Double) = x
-//}
+```scala sc-compile-with:1
 Meter(10) == Second(10)
 ```
 

docs/docs/reference/other-new-features/opaques.md

@@ -6,7 +6,7 @@ movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features/opaques
 
 Opaque types aliases provide type abstraction without any overhead. Example:
 
-```scala
+```scala sc-id:1
 object MyMath:
 
   opaque type Logarithm = Double
@@ -41,31 +41,7 @@ The public API of `Logarithm` consists of the `apply` and `safe` methods defined
 They convert from `Double`s to `Logarithm` values. Moreover, an operation `toDouble` that converts the other way, and operations `+` and `*` are defined as extension methods on `Logarithm` values.
 The following operations would be valid because they use functionality implemented in the `MyMath` object.
 
-```scala
-//{
-object MyMath:
-
-  opaque type Logarithm = Double
-
-  object Logarithm:
-
-    // These are the two ways to lift to the Logarithm type
-
-    def apply(d: Double): Logarithm = math.log(d)
-
-    def safe(d: Double): Option[Logarithm] =
-      if d > 0.0 then Some(math.log(d)) else None
-
-  end Logarithm
-
-  // Extension methods define opaque types' public APIs
-  extension (x: Logarithm)
-    def toDouble: Double = math.exp(x)
-    def + (y: Logarithm): Logarithm = Logarithm(math.exp(x) + math.exp(y))
-    def * (y: Logarithm): Logarithm = x + y
-
-end MyMath
-//}
+```scala sc-compile-with:1
 import MyMath.Logarithm
 
 val l = Logarithm(1.0)
@@ -76,31 +52,7 @@ val l4 = l + l2
 
 But the following operations would lead to type errors:
 
-```scala sc:fail
-//{
-object MyMath:
-
-  opaque type Logarithm = Double
-
-  object Logarithm:
-
-    // These are the two ways to lift to the Logarithm type
-
-    def apply(d: Double): Logarithm = math.log(d)
-
-    def safe(d: Double): Option[Logarithm] =
-      if d > 0.0 then Some(math.log(d)) else None
-
-  end Logarithm
-
-  // Extension methods define opaque types' public APIs
-  extension (x: Logarithm)
-    def toDouble: Double = math.exp(x)
-    def + (y: Logarithm): Logarithm = Logarithm(math.exp(x) + math.exp(y))
-    def * (y: Logarithm): Logarithm = x + y
-
-end MyMath
-//}
+```scala sc:fail sc-compile-with:1
 import MyMath.Logarithm
 
 val l = Logarithm(1.0)
@@ -114,7 +66,7 @@ l / l2                  // error: `/` is not a member of Logarithm
 
 Opaque type aliases can also come with bounds. Example:
 
-```scala
+```scala sc-id:2
 object Access:
 
   opaque type Permissions = Int
@@ -161,31 +113,7 @@ All three opaque type aliases have the same underlying representation type `Int`
 it known outside the `Access` object that `Permission` is a subtype of the other
 two types.  Hence, the following usage scenario type-checks.
 
-```scala
-//{
-object Access:
-
-  opaque type Permissions = Int
-  opaque type PermissionChoice = Int
-  opaque type Permission <: Permissions & PermissionChoice = Int
-
-  extension (x: Permissions)
-    def & (y: Permissions): Permissions = x | y
-  extension (x: PermissionChoice)
-    def | (y: PermissionChoice): PermissionChoice = x | y
-  extension (granted: Permissions)
-    def is(required: Permissions) = (granted & required) == required
-  extension (granted: Permissions)
-    def isOneOf(required: PermissionChoice) = (granted & required) != 0
-
-  val NoPermission: Permission = 0
-  val Read: Permission = 1
-  val Write: Permission = 2
-  val ReadWrite: Permissions = Read | Write
-  val ReadOrWrite: PermissionChoice = Read | Write
-
-end Access
-//}
+```scala sc-compile-with:2
 object User:
   import Access.*
 
@@ -214,7 +142,7 @@ since `Permissions` and `PermissionChoice` are different, unrelated types outsid
 While typically, opaque types are used together with objects to hide implementation details of a module, they can also be used with classes.
 
 For example, we can redefine the above example of Logarithms as a class.
-```scala
+```scala sc-id:3
 class Logarithms:
 
   opaque type Logarithm = Double
@@ -228,19 +156,7 @@ class Logarithms:
 ```
 
 Opaque type members of different instances are treated as different:
-```scala sc:fail
-//{
-class Logarithms:
-
-  opaque type Logarithm = Double
-
-  def apply(d: Double): Logarithm = math.log(d)
-
-  def safe(d: Double): Option[Logarithm] =
-    if d > 0.0 then Some(math.log(d)) else None
-
-  def mul(x: Logarithm, y: Logarithm) = x + y
-//}
+```scala sc:fail sc-compile-with:3
 val l1 = new Logarithms
 val l2 = new Logarithms
 val x = l1(1.5)