Merge pull request #10878 from dotty-staging/fix-docs

Docs cleanups

Author: b-studios

docs/docs/internals/explicit-nulls.md

@@ -76,10 +76,9 @@ Within `Types.scala`, we defined some extractors to work with nullable unions:
 `OrNull` and `OrUncheckedNull`.
 
 ```scala
-(tp: Type) match {
-  case OrNull(tp1) => // if tp is a nullable union: tp1 | Null
-  case _ => // otherwise
-}
+(tp: Type) match
+   case OrNull(tp1) => // if tp is a nullable union: tp1 | Null
+   case _ => // otherwise
 ```
 
 This extractor will call utility methods in `NullOpsDecorator.scala`. All of these
@@ -112,30 +111,25 @@ The reason for casting to `x.type & T`, as opposed to just `T`, is that it allow
 support flow typing for paths of length greater than one.
 
 ```scala
-abstract class Node {
-  val x: String
-  val next: Node | Null
-}
-
-def f = {
-  val l: Node|Null = ???
-  if (l != null && l.next != null) {
-    val third: l.next.next.type = l.next.next
-  }
-}
+abstract class Node:
+   val x: String
+   val next: Node | Null
+
+def f =
+   val l: Node|Null = ???
+   if l != null && l.next != null then
+      val third: l.next.next.type = l.next.next
 ```
 
 After typing, `f` becomes:
 
 ```scala
-def f = {
-  val l: Node|Null = ???
-  if (l != null && l.$asInstanceOf$[l.type & Node].next != null) {
-    val third:
-      l.$asInstanceOf$[l.type & Node].next.$asInstanceOf$[(l.type & Node).next.type & Node].next.type =
-      l.$asInstanceOf$[l.type & Node].next.$asInstanceOf$[(l.type & Node).next.type & Node].next
-  }
-}
+def f =
+   val l: Node|Null = ???
+   if l != null && l.$asInstanceOf$[l.type & Node].next != null then
+      val third:
+         l.$asInstanceOf$[l.type & Node].next.$asInstanceOf$[(l.type & Node).next.type & Node].next.type =
+         l.$asInstanceOf$[l.type & Node].next.$asInstanceOf$[(l.type & Node).next.type & Node].next
 ```
 Notice that in the example above `(l.type & Node).next.type & Node` is still a stable path, so
 we can use it in the type and track it for flow typing.

docs/docs/internals/syntax.md

@@ -104,10 +104,8 @@ yield
 ### Soft keywords
 
 ```
-as  derives  end  extension  inline  opaque  open  transparent  using
-*  +  -
+derives  end  extension  inline  infix  opaque  open  transparent  using  |  *  +  -
 ```
-
 ## Context-free Syntax
 
 The context-free syntax of Scala is given by the following EBNF

docs/docs/reference/changed-features/compiler-plugins.md

@@ -62,33 +62,30 @@ import dotty.tools.dotc.core.Symbols._
 import dotty.tools.dotc.plugins.{PluginPhase, StandardPlugin}
 import dotty.tools.dotc.transform.{Pickler, Staging}
 
-class DivideZero extends StandardPlugin {
-  val name: String = "divideZero"
-  override val description: String = "divide zero check"
-
-  def init(options: List[String]): List[PluginPhase] =
-    (new DivideZeroPhase) :: Nil
-}
-
-class DivideZeroPhase extends PluginPhase {
-  import tpd._
-
-  val phaseName = "divideZero"
-
-  override val runsAfter = Set(Pickler.name)
-  override val runsBefore = Set(Staging.name)
-
-  override def transformApply(tree: Apply)(implicit ctx: Context): Tree = {
-    tree match {
-      case Apply(Select(rcvr, nme.DIV), List(Literal(Constant(0))))
-          if rcvr.tpe <:< defn.IntType =>
-        report.error("dividing by zero", tree.pos)
-      case _ =>
-        ()
-    }
-    tree
-  }
-}
+class DivideZero extends StandardPlugin:
+   val name: String = "divideZero"
+   override val description: String = "divide zero check"
+
+   def init(options: List[String]): List[PluginPhase] =
+      (new DivideZeroPhase) :: Nil
+
+class DivideZeroPhase extends PluginPhase:
+   import tpd._
+
+   val phaseName = "divideZero"
+
+   override val runsAfter = Set(Pickler.name)
+   override val runsBefore = Set(Staging.name)
+
+   override def transformApply(tree: Apply)(implicit ctx: Context): Tree =
+      tree match
+         case Apply(Select(rcvr, nme.DIV), List(Literal(Constant(0))))
+         if rcvr.tpe <:< defn.IntType =>
+            report.error("dividing by zero", tree.pos)
+         case _ =>
+            ()
+      tree
+end DivideZeroPhase
 ```
 
 The plugin main class (`DivideZero`) must extend the trait `StandardPlugin`
@@ -111,13 +108,13 @@ import dotty.tools.dotc.core.Contexts.Context
 import dotty.tools.dotc.core.Phases.Phase
 import dotty.tools.dotc.plugins.ResearchPlugin
 
-class DummyResearchPlugin extends ResearchPlugin {
-  val name: String = "dummy"
-  override val description: String = "dummy research plugin"
+class DummyResearchPlugin extends ResearchPlugin:
+   val name: String = "dummy"
+   override val description: String = "dummy research plugin"
 
-  def init(options: List[String], phases: List[List[Phase]])(implicit ctx: Context): List[List[Phase]] =
-    phases
-}
+   def init(options: List[String], phases: List[List[Phase]])(implicit ctx: Context): List[List[Phase]] =
+      phases
+end DummyResearchPlugin
 ```
 
 A research plugin must extend the trait `ResearchPlugin`  and implement the

docs/docs/reference/changed-features/implicit-conversions-spec.md

@@ -17,7 +17,7 @@ The standard library defines an abstract class `Conversion`:
 package scala
 @java.lang.FunctionalInterface
 abstract class Conversion[-T, +U] extends Function1[T, U]:
-  def apply(x: T): U
+   def apply(x: T): U
 ```
 
 Function literals are automatically converted to `Conversion` values.

docs/docs/reference/changed-features/implicit-conversions.md

@@ -34,7 +34,7 @@ method that expects a `java.lang.Integer`
 ```scala
 import scala.language.implicitConversions
 implicit def int2Integer(x: Int): java.lang.Integer =
-  x.asInstanceOf[java.lang.Integer]
+   x.asInstanceOf[java.lang.Integer]
 ```
 
 The second example shows how to use `Conversion` to define an
@@ -44,12 +44,11 @@ types:
 ```scala
 import scala.language.implicitConversions
 implicit def ordT[T, S](
-  implicit conv: Conversion[T, S],
-           ordS: Ordering[S]
-  ): Ordering[T] = {
-  // `ordS` compares values of type `S`, but we can convert from `T` to `S`
-  (x: T, y: T) => ordS.compare(x, y)
-}
+      implicit conv: Conversion[T, S],
+               ordS: Ordering[S]
+   ): Ordering[T] =
+    // `ordS` compares values of type `S`, but we can convert from `T` to `S`
+   (x: T, y: T) => ordS.compare(x, y)
 
 class A(val x: Int) // The type for which we want an `Ordering`
 

docs/docs/reference/changed-features/implicit-resolution.md

@@ -11,25 +11,25 @@ affect implicits on the language level.
 must be explicitly declared. Excepted are only values in local blocks
 where the type may still be inferred:
 ```scala
-   class C {
+  class C {
 
-   val ctx: Context = ...        // ok
+     val ctx: Context = ...        // ok
 
-   /*!*/ implicit val x = ...    // error: type must be given explicitly
+     /*!*/ implicit val x = ...    // error: type must be given explicitly
 
-   /*!*/ implicit def y = ...    // error: type must be given explicitly
-
-   val y = {
+     /*!*/ implicit def y = ...    // error: type must be given explicitly
+  }
+  val y = {
      implicit val ctx = this.ctx // ok
      ...
-   }
+  }
 ```
 **2.** Nesting is now taken into account for selecting an implicit. Consider for instance the following scenario:
 ```scala
   def f(implicit i: C) = {
-    def g(implicit j: C) = {
-      implicitly[C]
-    }
+     def g(implicit j: C) = {
+        implicitly[C]
+     }
   }
 ```
 This will now resolve the `implicitly` call to `j`, because `j` is nested
@@ -41,12 +41,12 @@ no longer applies.
 **3.** Package prefixes no longer contribute to the implicit search scope of a type. Example:
 ```scala
   package p
+
   given a: A = A()
 
-  object o {
-    given b: B = B()
-    type C
-  }
+  object o:
+     given b: B = B()
+     type C
 ```
 Both `a` and `b` are visible as implicits at the point of the definition
 of `type C`. However, a reference to `p.o.C` outside of package `p` will

docs/docs/reference/changed-features/main-functions.md

@@ -7,22 +7,19 @@ Scala 3 offers a new way to define programs that can be invoked from the command
 A `@main` annotation on a method turns this method into an executable program.
 Example:
 ```scala
-@main def happyBirthday(age: Int, name: String, others: String*) = {
-  val suffix =
-    (age % 100) match {
+@main def happyBirthday(age: Int, name: String, others: String*) =
+   val suffix =
+      age % 100 match
       case 11 | 12 | 13 => "th"
       case _ =>
-        (age % 10) match {
-          case 1 => "st"
-          case 2 => "nd"
-          case 3 => "rd"
-          case _ => "th"
-        }
-    }
-  val bldr = new StringBuilder(s"Happy $age$suffix birthday, $name")
-  for other <- others do bldr.append(" and ").append(other)
-  bldr.toString
-}
+         age % 10 match
+         case 1 => "st"
+         case 2 => "nd"
+         case 3 => "rd"
+         case _ => "th"
+   val bldr = new StringBuilder(s"Happy $age$suffix birthday, $name")
+   for other <- others do bldr.append(" and ").append(other)
+   bldr.toString
 ```
 This would generate a main program `happyBirthday` that could be called like this
 ```
@@ -59,29 +56,26 @@ The Scala compiler generates a program from a `@main` method `f` as follows:
 
 For instance, the `happyBirthDay` method above would generate additional code equivalent to the following class:
 ```scala
-final class happyBirthday {
-  import scala.util.{CommandLineParser => CLP}
-  <static> def main(args: Array[String]): Unit =
-    try
-      happyBirthday(
-          CLP.parseArgument[Int](args, 0),
-          CLP.parseArgument[String](args, 1),
-          CLP.parseRemainingArguments[String](args, 2))
-    catch {
-      case error: CLP.ParseError => CLP.showError(error)
-    }
-}
+final class happyBirthday:
+   import scala.util.{CommandLineParser => CLP}
+   <static> def main(args: Array[String]): Unit =
+      try
+         happyBirthday(
+            CLP.parseArgument[Int](args, 0),
+            CLP.parseArgument[String](args, 1),
+            CLP.parseRemainingArguments[String](args, 2))
+      catch
+         case error: CLP.ParseError => CLP.showError(error)
 ```
 **Note**: The `<static>` modifier above expresses that the `main` method is generated
 as a static method of class `happyBirthDay`. It is not available for user programs in Scala. Regular "static" members are generated in Scala using objects instead.
 
 `@main` methods are the recommended scheme to generate programs that can be invoked from the command line in Scala 3. They replace the previous scheme to write program as objects with a special `App` parent class. In Scala 2, `happyBirthday` could be written also like this:
 
 ```scala
-object happyBirthday extends App {
-  // needs by-hand parsing of arguments vector
-  ...
-}
+object happyBirthday extends App:
+   // needs by-hand parsing of arguments vector
+   ...
 ```
 
 The previous functionality of `App`, which relied on the "magic" `DelayedInit` trait, is no longer available. `App` still exists in limited form for now, but it does not support command line arguments and will be deprecated in the future. If programs need to cross-build

docs/docs/reference/changed-features/match-syntax.md

@@ -10,21 +10,31 @@ The syntactical precedence of match expressions has been changed.
 
     ```scala
     xs match {
-      case Nil => "empty"
-      case x :: xs1 => "nonempty"
+       case Nil => "empty"
+       case x :: xs1 => "nonempty"
     } match {
-      case "empty" => 0
-      case "nonempty" => 1
+       case "empty" => 0
+       case "nonempty" => 1
     }
     ```
 
+  (or, dropping the optional braces)
+
+    ```scala
+    xs match
+       case Nil => "empty"
+       case x :: xs1 => "nonempty"
+    match
+       case "empty" => 0
+       case "nonempty" => 1
+    ```
+
  2. `match` may follow a period:
 
      ```scala
-     if xs.match {
-       case Nil => false
-       case _ => true
-     }
+     if xs.match
+        case Nil => false
+        case _ => true
      then "nonempty"
      else "empty"
      ```