Merge pull request #10767 from michelou/scala3-docs

[docs/reference] fixed many issues in MarkDown files

Author: liufengyun

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

@@ -66,7 +66,8 @@ 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
+  def init(options: List[String]): List[PluginPhase] =
+    (new DivideZeroPhase) :: Nil
 }
 
 class DivideZeroPhase extends PluginPhase {

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

@@ -24,7 +24,7 @@ where the type may still be inferred:
       ...
    }
 ```
-**2.** Nesting is now taken into account for selecting an implicit.Consider for instance the following scenario:
+**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) = {
@@ -55,7 +55,7 @@ have only `b` in its implicit search scope but not `a`.
 In more detail, here are the rules for what constitutes the implicit scope of
 a type:
 
-**Definition:** A reference is an _anchor_ if it refers to an object, a class, a trait, an abstract type, an opaque type alias, or a match type alias. References to packages and package objects are anchors only under -source:3.0-migration.
+**Definition:** A reference is an _anchor_ if it refers to an object, a class, a trait, an abstract type, an opaque type alias, or a match type alias. References to packages and package objects are anchors only under `-source:3.0-migration`.
 
 **Definition:** The _anchors_ of a type _T_ is a set of references defined as follows:
 
@@ -122,7 +122,7 @@ most (but not all) divergence errors in Scala 2 would terminate the implicit sea
   def buzz(y: A) = ???
   buzz(1)   // error: ambiguous
 ```
-**7.** The rule for picking a _most specific_ alternative among a set of overloaded or implicit alternatives is refined to take context parameters into account. All else being equal, an alternative that takes some context parameters is taken to be less specific than an alternative that takes none. If both alternatives take context parameters, we try to choose between them as if they were methods with regular parameters. The following paragraph in the SLS is affected by this change:
+**7.** The rule for picking a _most specific_ alternative among a set of overloaded or implicit alternatives is refined to take context parameters into account. All else being equal, an alternative that takes some context parameters is taken to be less specific than an alternative that takes none. If both alternatives take context parameters, we try to choose between them as if they were methods with regular parameters. The following paragraph in the [SLS §6.26.3](https://scala-lang.org/files/archive/spec/2.13/06-expressions.html#overloading-resolution) is affected by this change:
 
 _Original version:_
 

docs/docs/reference/changed-features/interpolation-escapes.md

@@ -3,7 +3,7 @@ layout: doc-page
 title: Escapes in interpolations
 ---
 
-In Scala 2 there was no straightforward way to represent a single quote character `"` in a single quoted interpolation. A \ character can't be used for that because interpolators themselves decide how to handle escaping, so the parser doesn't know whether the " should be escaped or used as a terminator.
+In Scala 2 there was no straightforward way to represent a single quote character `"` in a single quoted interpolation. A `\` character can't be used for that because interpolators themselves decide how to handle escaping, so the parser doesn't know whether the `"` should be escaped or used as a terminator.
 
 In Dotty, you can use the `$` meta character of interpolations to escape a `"` character.
 

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

@@ -16,6 +16,7 @@ The syntactical precedence of match expressions has been changed.
       case "empty" => 0
       case "nonempty" => 1
     }
+    ```
 
  2. `match` may follow a period:
 
@@ -26,6 +27,7 @@ The syntactical precedence of match expressions has been changed.
      }
      then "nonempty"
      else "empty"
+     ```
 
  3. The scrutinee of a match expression must be an `InfixExpr`. Previously the scrutinee could be followed by a type ascription `: T`, but this is no longer supported. So `x : T match { ... }` now has to be
  written `(x: T) match { ... }`.

docs/docs/reference/changed-features/numeric-literals.md

@@ -79,8 +79,8 @@ numbers that can have both a decimal point and an exponent:
 ```scala
 object FromDigits {
 
-  /** A subclass of `FromDigits` that also allows to convert whole number literals
-   *  with a radix other than 10
+  /** A subclass of `FromDigits` that also allows to convert whole
+   *  number literals with a radix other than 10
    */
   trait WithRadix[T] extends FromDigits[T] {
     def fromDigits(digits: String): T = fromDigits(digits, 10)

docs/docs/reference/changed-features/operators.md

@@ -47,7 +47,7 @@ one of the following conditions holds:
  - the operator is followed by an opening brace.
 
 An alphanumeric operator is an operator consisting entirely of letters, digits, the `$` and `_` characters, or
-any unicode character `c` for which `java.lang.Character.isIdentifierPart(c)` returns `true`.
+any Unicode character `c` for which `java.lang.Character.isIdentifierPart(c)` returns `true`.
 
 Infix operations involving symbolic operators are always allowed, so `infix` is redundant for methods with symbolic names.
 
@@ -89,9 +89,9 @@ The purpose of the `infix` modifier is to achieve consistency across a code base
  5. To smooth migration to Scala 3.0, alphanumeric operators will only be deprecated from Scala 3.1 onwards,
 or if the `-source 3.1` option is given in Dotty/Scala 3.
 
-## The @targetName Annotation
+## The `@targetName` Annotation
 
-It is recommended that definitions of symbolic operators carry a [@targetName annotation](../other-new-features/targetName.html) that provides an encoding of the operator with an alphanumeric name. This has several benefits:
+It is recommended that definitions of symbolic operators carry a [`@targetName` annotation](../other-new-features/targetName.md) that provides an encoding of the operator with an alphanumeric name. This has several benefits:
 
  - It helps interoperability between Scala and other languages. One can call
    a Scala-defined symbolic operator from another language using its target name,
@@ -115,7 +115,7 @@ def condition =
   || xs.exists(_ > 0)
   || xs.isEmpty
 ```
-Previously, these expressions would have been rejected, since the compiler's semicolon inference
+Previously, those expressions would have been rejected, since the compiler's semicolon inference
 would have treated the continuations `++ " world"` or `|| xs.isEmpty` as separate statements.
 
 To make this syntax work, the rules are modified to not infer semicolons in front of leading infix operators.

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

@@ -13,8 +13,8 @@ are in the first argument list.
 
 Overloading resolution now can take argument lists into account when
 choosing among a set of overloaded alternatives.
-For example, the following code compiles in Dotty, while it results in an
-ambiguous overload error in Scala2:
+For example, the following code compiles in Scala 3, while it results in an
+ambiguous overload error in Scala 2:
 
 ```scala
 def f(x: Int)(y: String): Int = 0
@@ -33,7 +33,7 @@ g(2)(3)(4)     // ok
 g(2)(3)("")    // ok
 ```
 
-To make this work, the rules for overloading resolution in section 6.23.3 of the SLS are augmented
+To make this work, the rules for overloading resolution in [SLS §6.26.3](https://www.scala-lang.org/files/archive/spec/2.13/06-expressions.html#overloading-resolution) are augmented
 as follows:
 
 > In a situation where a function is applied to more than one argument list, if overloading
@@ -57,7 +57,7 @@ def f(x: String, f2: String => String) = f2(x)
 f("a", _.toUpperCase)
 f(2, _ * 2)
 ```
-To make this work, the rules for overloading resolution in section 6.23.3 of the SLS are modified
+To make this work, the rules for overloading resolution in [SLS §6.26.3](https://www.scala-lang.org/files/archive/spec/2.13/06-expressions.html#overloading-resolution) are modified
 as follows:
 
 Replace the sentence

docs/docs/reference/changed-features/pattern-bindings.md

@@ -25,13 +25,13 @@ want to decompose it like this:
 ```scala
 val first :: rest = elems   // error
 ```
-This works in Scala 2. In fact it is a typical use case for Scala 2's rules. But in Scala 3.1 it will give a type error. One can avoid the error by marking the pattern with an @unchecked annotation:
+This works in Scala 2. In fact it is a typical use case for Scala 2's rules. But in Scala 3.1 it will give a type error. One can avoid the error by marking the pattern with an `@unchecked` annotation:
 ```scala
 val first :: rest : @unchecked = elems   // OK
 ```
 This will make the compiler accept the pattern binding. It might give an error at runtime instead, if the underlying assumption that `elems` can never be empty is wrong.
 
-## Pattern Bindings in For Expressions
+## Pattern Bindings in `for` Expressions
 
 Analogous changes apply to patterns in `for` expressions. For instance:
 

docs/docs/reference/changed-features/pattern-matching.md

@@ -3,9 +3,9 @@ layout: doc-page
 title: "Option-less pattern matching"
 ---
 
-Dotty implementation of pattern matching was greatly simplified compared to scalac. From a user perspective, this means that Dotty generated patterns are a *lot* easier to debug, as variables all show up in debug modes and positions are correctly preserved.
+Dotty implementation of pattern matching was greatly simplified compared to Scala 2. From a user perspective, this means that Scala 3 generated patterns are a *lot* easier to debug, as variables all show up in debug modes and positions are correctly preserved.
 
-Dotty supports a superset of scalac's [extractors](https://www.scala-lang.org/files/archive/spec/2.13/08-pattern-matching.html#extractor-patterns).
+Dotty supports a superset of Scala 2 [extractors](https://www.scala-lang.org/files/archive/spec/2.13/08-pattern-matching.html#extractor-patterns).
 
 ## Extractors
 
@@ -54,7 +54,7 @@ A usage of a fixed-arity extractor is irrefutable if one of the following condit
 
 - `U = true`
 - the extractor is used as a product match
-- `U = Some[T]` (for Scala2 compatibility)
+- `U = Some[T]` (for Scala 2 compatibility)
 - `U <: R` and `U <: { def isEmpty: false }`
 
 ### Variadic Extractors
@@ -84,7 +84,7 @@ and `S` conforms to one of the two matches above.
 The former form of `unapplySeq` has higher priority, and _sequence match_ has higher
 precedence over _product-sequence match_.
 
-A usage of a variadic extractor is irrefutable if one of the following condition holds:
+A usage of a variadic extractor is irrefutable if one of the following conditions holds:
 
 - the extractor is used directly as a sequence match or product-sequence match
 - `U = Some[T]` (for Scala2 compatibility)
@@ -230,7 +230,8 @@ object CharList {
 ```Scala
 class Foo(val name: String, val children: Int *)
 object Foo {
-  def unapplySeq(f: Foo): Option[(String, Seq[Int])] = Some((f.name, f.children))
+  def unapplySeq(f: Foo): Option[(String, Seq[Int])] =
+    Some((f.name, f.children))
 }
 
 def foo(f: Foo) = f match {

docs/docs/reference/changed-features/structural-types.md

@@ -42,7 +42,7 @@ Here's an example of a structural type `Person`:
     val age: Int
   }
 ```
-The person type adds a _refinement_ to its parent type `Record` that defines `name` and `age` fields. We say the refinement is _structural_ since  `name` and `age` are not defined in the parent type. But they exist nevertheless as members of class `Person`. For instance, the following
+The type `Person` adds a _refinement_ to its parent type `Record` that defines the two fields `name` and `age`. We say the refinement is _structural_ since  `name` and `age` are not defined in the parent type. But they exist nevertheless as members of class `Person`. For instance, the following
 program would print  "Emma is 42 years old.":
 ```scala
   val person = Record("name" -> "Emma", "age" -> 42).asInstanceOf[Person]