Merge pull request #10826 from michelou/scala3-docs

[docs/reference] more fixes in Markdown files

Author: liufengyun

docs/docs/reference/changed-features/eta-expansion-spec.md

@@ -3,11 +3,13 @@ layout: doc-page
 title: "Automatic Eta Expansion - More Details"
 ---
 
-### Motivation
+## Motivation
 
 Scala maintains a convenient distinction between _methods_ and _functions_.
 Methods are part of the definition of a class that can be invoked in objects while functions are complete objects themselves, making them first-class entities. For example, they can be assigned to variables.
-These two mechanisms are bridged in Scala by a mechanism called _eta-expansion_ (also called eta-abstraction), which converts a reference to a method into a function. Intuitively, a method `m` can be passed around by turning it into an object: the function `x => m(x)`.
+These two mechanisms are bridged in Scala by a mechanism called
+[_eta-expansion_](https://www.scala-lang.org/files/archive/spec/2.13/06-expressions.html#eta-expansion-section)
+(also called eta-abstraction), which converts a reference to a method into a function. Intuitively, a method `m` can be passed around by turning it into an object: the function `x => m(x)`.
 
 In this snippet which assigns a method to a `val`, the compiler will perform _automatic eta-expansion_, as shown in the comment:
 
@@ -69,6 +71,6 @@ Thus, an unapplied method with an empty argument list is only converted to a fun
 
 The method value syntax `m _` is deprecated.
 
-### Reference
+## Reference
 
 For more info, see [PR #2701](https://github.com/lampepfl/dotty/pull/2701).

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

@@ -16,7 +16,8 @@ The standard library defines an abstract class `Conversion`:
 ```scala
 package scala
 @java.lang.FunctionalInterface
-abstract class Conversion[-T, +U] extends Function1[T, U]
+abstract class Conversion[-T, +U] extends Function1[T, U]:
+  def apply(x: T): U
 ```
 
 Function literals are automatically converted to `Conversion` values.
@@ -80,8 +81,8 @@ implicit val myConverter: Int => String = _.toString
 implicit val myConverter: Conversion[Int, String] = _.toString
 ```
 
-Note that implicit conversions are also  affected by the [changes to
-implicit resolution](implicit-resolution.md) between Scala 2 and
+Note that implicit conversions are also affected by the
+[changes to implicit resolution](implicit-resolution.md) between Scala 2 and
 Scala 3.
 
 ## Motivation for the changes

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

@@ -2,7 +2,7 @@
 layout: doc-page
 title: "Changes in Implicit Resolution"
 ---
-This page describes changes to the implicit resolution that apply both to the new `given`s and to the old-style `implicit`s in Scala 3.
+This section describes changes to the implicit resolution that apply both to the new `given`s and to the old-style `implicit`s in Scala 3.
 Implicit resolution uses a new algorithm which caches implicit results
 more aggressively for performance. There are also some changes that
 affect implicits on the language level.
@@ -20,8 +20,8 @@ where the type may still be inferred:
    /*!*/ implicit def y = ...    // error: type must be given explicitly
 
    val y = {
-      implicit val ctx = this.ctx // ok
-      ...
+     implicit val ctx = this.ctx // ok
+     ...
    }
 ```
 **2.** Nesting is now taken into account for selecting an implicit. Consider for instance the following scenario:
@@ -114,7 +114,7 @@ the implicit search for `Q` fails.
 **5.** The treatment of divergence errors has also changed. A divergent implicit is treated as a normal failure, after which alternatives are still tried. This also makes sense: Encountering a divergent implicit means that we assume that no finite solution can be found on the corresponding path, but another path can still be tried. By contrast,
 most (but not all) divergence errors in Scala 2 would terminate the implicit search as a whole.
 
-**6.** Scala-2 gives a lower level of priority to implicit conversions with call-by-name parameters relative to implicit conversions with call-by-value parameters. Scala 3 drops this distinction. So the following code snippet would be ambiguous in Scala 3:
+**6.** Scala 2 gives a lower level of priority to implicit conversions with call-by-name parameters relative to implicit conversions with call-by-value parameters. Scala 3 drops this distinction. So the following code snippet would be ambiguous in Scala 3:
 
 ```scala
   implicit def conv1(x: Int): A = new A(x)

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

@@ -16,8 +16,8 @@ def unapply[A](x: T)(implicit x: B): U
 def unapplySeq[A](x: T)(implicit x: B): U
 ```
 
-Extractors expose the method `unapply` are called fixed-arity extractors, which
-work with patterns of fixed arity. Extractors expose the method `unapplySeq` are
+Extractors that expose the method `unapply` are called fixed-arity extractors, which
+work with patterns of fixed arity. Extractors that expose the method `unapplySeq` are
 called variadic extractors, which enables variadic patterns.
 
 ### Fixed-Arity Extractors
@@ -93,7 +93,7 @@ A usage of a variadic extractor is irrefutable if one of the following condition
 ## Boolean Match
 
 - `U =:= Boolean`
-- Pattern-matching on exactly `0` patterns
+- Pattern-matching on exactly `0` pattern
 
 For example:
 
@@ -250,4 +250,4 @@ Abstract type testing with `ClassTag` is replaced with `TypeTest` or the alias `
 - pattern `_: X` for an abstract type requires a `TypeTest` in scope
 - pattern `x @ X()` for an unapply that takes an abstract type requires a `TypeTest` in scope
 
-[More details on TypeTest](../other-new-features/type-test.md)
+[More details on `TypeTest`](../other-new-features/type-test.md)

docs/docs/reference/contextual/context-bounds.md

@@ -9,7 +9,7 @@ A context bound is a shorthand for expressing the common pattern of a context pa
 def maximum[T: Ord](xs: List[T]): T = xs.reduceLeft(max)
 ```
 
-A bound like `: Ord` on a type parameter `T` of a method or class indicates a context parameter `with Ord[T]`. The context parameter(s) generated from context bounds come last in the definition of the containing method or class. E.g.,
+A bound like `: Ord` on a type parameter `T` of a method or class indicates a context parameter `with Ord[T]`. The context parameter(s) generated from context bounds come last in the definition of the containing method or class. For instance,
 
 ```scala
 def f[T: C1 : C2, U: C3](x: T)(using y: U, z: V): R

docs/docs/reference/contextual/context-functions.md

@@ -125,10 +125,11 @@ object PostConditions {
 
   def result[T](using r: WrappedResult[T]): T = r
 
-  extension [T](x: T) def ensuring(condition: WrappedResult[T] ?=> Boolean): T = {
-    assert(condition(using x))
-    x
-  }
+  extension [T](x: T)
+    def ensuring(condition: WrappedResult[T] ?=> Boolean): T = {
+      assert(condition(using x))
+      x
+    }
 }
 import PostConditions.{ensuring, result}
 

docs/docs/reference/contextual/conversions.md

@@ -6,7 +6,8 @@ title: "Implicit Conversions"
 Implicit conversions are defined by given instances of the `scala.Conversion` class.
 This class is defined in package `scala` as follows:
 ```scala
-abstract class Conversion[-T, +U] extends (T => U)
+abstract class Conversion[-T, +U] extends (T => U):
+  def apply (x: T): U
 ```
 For example, here is an implicit conversion from `String` to `Token`:
 ```scala
@@ -41,7 +42,7 @@ given int2Integer: Conversion[Int, java.lang.Integer] =
  java.lang.Integer.valueOf(_)
 ```
 
-2. The "magnet" pattern is sometimes used to express many variants of a method. Instead of defining overloaded versions of the method, one can also let the method take one or more arguments of specially defined "magnet" types, into which various argument types can be converted. E.g.
+2. The "magnet" pattern is sometimes used to express many variants of a method. Instead of defining overloaded versions of the method, one can also let the method take one or more arguments of specially defined "magnet" types, into which various argument types can be converted. Example:
 ```scala
 object Completions {
 

docs/docs/reference/contextual/derivation-macro.md

@@ -91,12 +91,13 @@ The implementation of `summonAll` as a macro can be show below assuming that we
 have the given instances for our primitive types:
 
 ```scala
-  def summonAll[T: Type](using Quotes): List[Expr[Eq[_]]] = Type.of[T] match {
-    case '[String *: tpes] => '{ summon[Eq[String]] }  :: summonAll[tpes]
-    case '[Int *: tpes]    => '{ summon[Eq[Int]] }     :: summonAll[tpes]
-    case '[tpe *: tpes]   => derived[tpe] :: summonAll[tpes]
-    case '[EmptyTuple] => Nil
-  }
+  def summonAll[T: Type](using Quotes): List[Expr[Eq[_]]] =
+    Type.of[T] match {
+      case '[String *: tpes] => '{ summon[Eq[String]] } :: summonAll[tpes]
+      case '[Int *: tpes]    => '{ summon[Eq[Int]] }    :: summonAll[tpes]
+      case '[tpe *: tpes]    => derived[tpe] :: summonAll[tpes]
+      case '[EmptyTuple]     => Nil
+    }
 ```
 
 One additional difference with the body of `derived` here as opposed to the one
@@ -169,12 +170,13 @@ object Eq {
       def eqv(x: T, y: T): Boolean = body(x, y)
     }
 
-  def summonAll[T: Type](using Quotes): List[Expr[Eq[_]]] = Type.of[T] match {
-    case '[String *: tpes] => '{ summon[Eq[String]] }  :: summonAll[tpes]
-    case '[Int *: tpes]    => '{ summon[Eq[Int]] }     :: summonAll[tpes]
-    case '[tpe *: tpes]   => derived[tpe] :: summonAll[tpes]
-    case '[EmptyTuple] => Nil
-  }
+  def summonAll[T: Type](using Quotes): List[Expr[Eq[_]]] =
+    Type.of[T] match {
+      case '[String *: tpes] => '{ summon[Eq[String]] } :: summonAll[tpes]
+      case '[Int *: tpes]    => '{ summon[Eq[Int]] }    :: summonAll[tpes]
+      case '[tpe *: tpes]    => derived[tpe] :: summonAll[tpes]
+      case '[EmptyTuple]     => Nil
+    }
 
   given derived[T: Type](using q: Quotes): Expr[Eq[T]] = {
     import quotes.reflect._

docs/docs/reference/contextual/derivation.md

@@ -63,12 +63,16 @@ object Mirror {
   /** The Mirror for a product type */
   trait Product extends Mirror {
 
-    /** Create a new instance of type `T` with elements taken from product `p`. */
+    /** Create a new instance of type `T` with elements
+     *  taken from product `p`.
+     */
     def fromProduct(p: scala.Product): MirroredMonoType
   }
 
   trait Sum extends Mirror { self =>
-    /** The ordinal number of the case class of `x`. For enums, `ordinal(x) == x.ordinal` */
+    /** The ordinal number of the case class of `x`.
+     *  For enums, `ordinal(x) == x.ordinal`
+     */
     def ordinal(x: MirroredMonoType): Int
   }
 }
@@ -199,10 +203,11 @@ implementation of `summonAll` is `inline` and uses Scala 3's `summonInline` cons
 
 ```scala
 
-inline def summonAll[T <: Tuple]: List[Eq[_]] = inline erasedValue[T] match {
-  case _: EmptyTuple => Nil
-  case _: (t *: ts) => summonInline[Eq[t]] :: summonAll[ts]
-}
+inline def summonAll[T <: Tuple]: List[Eq[_]] =
+  inline erasedValue[T] match {
+    case _: EmptyTuple => Nil
+    case _: (t *: ts) => summonInline[Eq[t]] :: summonAll[ts]
+  }
 ```
 
 with the instances for children in hand the `derived` method uses an `inline match` to dispatch to methods which can
@@ -243,10 +248,11 @@ Pulling this all together we have the following complete implementation,
 import scala.deriving._
 import scala.compiletime.{erasedValue, summonInline}
 
-inline def summonAll[T <: Tuple]: List[Eq[_]] = inline erasedValue[T] match {
-  case _: EmptyTuple => Nil
-  case _: (t *: ts) => summonInline[Eq[t]] :: summonAll[ts]
-}
+inline def summonAll[T <: Tuple]: List[Eq[_]] =
+  inline erasedValue[T] match {
+    case _: EmptyTuple => Nil
+    case _: (t *: ts) => summonInline[Eq[t]] :: summonAll[ts]
+  }
 
 trait Eq[T] {
   def eqv(x: T, y: T): Boolean

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

@@ -215,7 +215,8 @@ object List:
       def < (ys: List[T]): Boolean = ...
 end List
 
-// extension method available since it is in the implicit scope of List[List[Int]]
+// extension method available since it is in the implicit scope
+// of List[List[Int]]
 List(List(1, 2), List(3, 4)).flatten
 
 // extension method available since it is in the given Ordering[List[T]],