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]

docs/docs/reference/contextual/extension-methods.md

@@ -267,7 +267,7 @@ def position(s: String)(ch: Char, n: Int): Int =
 ### Syntax
 
 Here are the syntax changes for extension methods and collective extensions relative
-to the [current syntax](../../internals/syntax.md).
+to the [current syntax](../syntax.md).
 
 ```
 BlockStat         ::=  ... | Extension

docs/docs/reference/contextual/given-imports.md

@@ -18,7 +18,7 @@ object B {
 }
 ```
 
-In the code above, the `import A._` clause of object `B` will import all members
+In the code above, the `import A._` clause in object `B` imports all members
 of `A` _except_ the given instance `tc`. Conversely, the second import `import A.given` will import _only_ that given instance.
 The two import clauses can also be merged into one:
 
@@ -67,7 +67,7 @@ object Instances {
 }
 ```
 
-the import
+the import clause
 
 ```scala
 import Instances.{given Ordering[?], given ExecutionContext}

docs/docs/reference/contextual/givens.md

@@ -4,7 +4,7 @@ title: "Given Instances"
 ---
 
 Given instances (or, simply, "givens") define "canonical" values of certain types
-that serve for synthesizing arguments to [context parameters](./using-clauses.html). Example:
+that serve for synthesizing arguments to [context parameters](./using-clauses.md). Example:
 
 ```scala
 trait Ord[T] {
@@ -34,7 +34,7 @@ for `Ord[List[T]]` for all types `T` that come with a given instance for `Ord[T]
 themselves. The `using` clause in `listOrd` defines a condition: There must be a
 given of type `Ord[T]` for a given of type `Ord[List[T]]` to exist.
 Such conditions are expanded by the compiler to [context
-parameters](./using-clauses.html).
+parameters](./using-clauses.md).
 
 ## Anonymous Givens
 
@@ -108,7 +108,7 @@ In each case, a pattern-bound given instance consists of `given` and a type `T`.
 
 ## Negated Givens
 
-Scala 2's somewhat puzzling behavior with respect to ambiguity has been exploited to implement the analogue of a "negated" search in implicit resolution, where a query Q1 fails if some other query Q2 succeeds and Q1 succeeds if Q2 fails. With the new cleaned up behavior these techniques no longer work. But there is now a new special type `scala.util.NotGiven` which implements negation directly.
+Scala 2's somewhat puzzling behavior with respect to ambiguity has been exploited to implement the analogue of a "negated" search in implicit resolution, where a query Q1 fails if some other query Q2 succeeds and Q1 succeeds if Q2 fails. With the new cleaned up behavior these techniques no longer work. But the new special type `scala.util.NotGiven` now implements negation directly.
 
 For any query type `Q`, `NotGiven[Q]` succeeds if and only if the implicit
 search for `Q` fails, for example:

docs/docs/reference/contextual/motivation.md

@@ -8,7 +8,7 @@ title: "Overview"
 Scala's implicits are its most distinguished feature. They are _the_ fundamental way to abstract over context. They represent a unified paradigm with a great variety of use cases, among them: implementing type classes, establishing context, dependency injection, expressing capabilities, computing new types and proving relationships between them.
 
 Following Haskell, Scala was the second popular language to have some form of implicits. Other languages have followed suit. E.g Rust's traits or Swift's protocol extensions. Design proposals are also on the table for Kotlin as [compile time dependency resolution](https://github.com/Kotlin/KEEP/blob/e863b25f8b3f2e9b9aaac361c6ee52be31453ee0/proposals/compile-time-dependency-resolution.md), for C# as [Shapes and Extensions](https://github.com/dotnet/csharplang/issues/164)
-or for F# as [Traits](https://github.com/MattWindsor91/visualfsharp/blob/hackathon-vs/examples/fsconcepts.md). Implicits are also a common feature of theorem provers such as Coq or Agda.
+or for F# as [Traits](https://github.com/MattWindsor91/visualfsharp/blob/hackathon-vs/examples/fsconcepts.md). Implicits are also a common feature of theorem provers such as Coq or [Agda](https://agda.readthedocs.io/en/latest/language/implicit-arguments.html).
 
 Even though these designs use widely different terminology, they are all variants of the core idea of _term inference_. Given a type, the compiler synthesizes a "canonical" term that has that type. Scala embodies the idea in a purer form than most other languages: An implicit parameter directly leads to an inferred argument term that could also be written down explicitly. By contrast, type class based designs are less direct since they hide term inference behind some form of type classification and do not offer the option of writing the inferred quantities (typically, dictionaries) explicitly.
 

docs/docs/reference/contextual/type-classes.md

@@ -97,7 +97,7 @@ assertTransformation(List("a1", "b1"), List("a", "b"), elt => s"${elt}1")
 ```
 
 That's a first step, but in practice we probably would like the `map` function to be a method directly accessible on the type `F`. So that we can call `map` directly on instances of `F`, and get rid of the `summon[Functor[F]]` part.
-As in the previous example of Monoids, [`extension` methods](extension-methods.html) help achieving that. Let's re-define the `Functor` type class with extension methods.
+As in the previous example of Monoids, [`extension` methods](extension-methods.md) help achieving that. Let's re-define the `Functor` type class with extension methods.
 
 ```scala
 trait Functor[F[_]]:
@@ -234,7 +234,7 @@ given configDependentMonad: Monad[ConfigDependent] with
 end configDependentMonad
 ```
 
-The type `ConfigDependent` can be written using [type lambdas](../new-types/type-lambdas.html):
+The type `ConfigDependent` can be written using [type lambdas](../new-types/type-lambdas.md):
 
 ```scala
 type ConfigDependent = [Result] =>> Config => Result