Merge pull request #10875 from michelou/scala3-docs

[docs/reference] more fixes in Markdown files

Author: liufengyun

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

@@ -102,7 +102,7 @@ val x: String = 1  // Scala 2: assigns "abc" to x
 This snippet contains a type error. The right hand side of `val x`
 does not conform to type `String`. In Scala 2, the compiler will use
 `m` as an implicit conversion from `Int` to `String`, whereas Scala 3
-will report a type error, because Map isn't an instance of
+will report a type error, because `Map` isn't an instance of
 `Conversion`.
 
 ## Migration path

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

@@ -1,6 +1,6 @@
 ---
 layout: doc-page
-title: Rules for Operators
+title: "Rules for Operators"
 ---
 
 The rules for infix operators have changed in some parts:

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

@@ -20,7 +20,7 @@ The standard library defines a universal marker trait `Selectable` in the packag
 trait Selectable extends Any
 ```
 
-An implementation of `Selectable` that relies on Java reflection is
+An implementation of `Selectable` that relies on [Java reflection](https://www.oracle.com/technical-resources/articles/java/javareflection.html) is
 available in the standard library: `scala.reflect.Selectable`. Other
 implementations can be envisioned for platforms where Java reflection
 is not available.

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

@@ -71,7 +71,7 @@ Besides `selectDynamic`, a `Selectable` class sometimes also defines a method `a
 
 ## Using Java Reflection
 
-Structural types can also be accessed using Java reflection. Example:
+Structural types can also be accessed using [Java reflection](https://www.oracle.com/technical-resources/articles/java/javareflection.html). Example:
 ```scala
   type Closeable = { def close(): Unit }
 

docs/docs/reference/changed-features/vararg-patterns.md

@@ -35,7 +35,7 @@ The change to the grammar is:
 
 ## Compatibility considerations
 
-To enable smooth cross compilation between Scala 2 and Scala 3, Dotty will
+To enable smooth cross compilation between Scala 2 and Scala 3, the compiler will
 accept both the old and the new syntax. Under the `-source 3.1` setting, an error
 will be emitted when the old syntax is encountered. They will be enabled by
 default in version 3.1 of the language.

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

@@ -106,7 +106,7 @@ check we want to generate is the following:
    && Eq[Int].eqv(x.productElement(1), y.productElement(1))
 ```
 
-### Calling the derived method inside the macro
+## Calling the derived method inside the macro
 
 Following the rules in [Macros](../metaprogramming/toc.md) we create two methods.
 One that hosts the top-level splice `eqv` and one that is the implementation.

docs/docs/reference/contextual/derivation.md

@@ -59,13 +59,13 @@ sealed trait Mirror:
 
 object Mirror:
 
-  /** The Mirror for a product type */
-  trait Product extends Mirror:
+   /** The Mirror for a product type */
+   trait Product extends Mirror:
 
-     /** Create a new instance of type `T` with elements
-      *  taken from product `p`.
-      */
-     def fromProduct(p: scala.Product): MirroredMonoType
+      /** Create a new instance of type `T` with elements
+       *  taken from product `p`.
+       */
+      def fromProduct(p: scala.Product): MirroredMonoType
 
    trait Sum extends Mirror:
 
@@ -125,12 +125,12 @@ Note the following properties of `Mirror` types,
 + The kinds of `MirroredType` and `MirroredElemTypes` match the kind of the data type the mirror is an instance for.
   This allows `Mirrors` to support ADTs of all kinds.
 + There is no distinct representation type for sums or products (ie. there is no `HList` or `Coproduct` type as in
-  Scala 2 versions of shapeless). Instead the collection of child types of a data type is represented by an ordinary,
+  Scala 2 versions of Shapeless). Instead the collection of child types of a data type is represented by an ordinary,
   possibly parameterized, tuple type. Scala 3's metaprogramming facilities can be used to work with these tuple types
   as-is, and higher level libraries can be built on top of them.
 + For both product and sum types, the elements of `MirroredElemTypes` are arranged in definition order (i.e. `Branch[T]`
   precedes `Leaf[T]` in `MirroredElemTypes` for `Tree` because `Branch` is defined before `Leaf` in the source file).
-  This means that `Mirror.Sum` differs in this respect from shapeless's generic representation for ADTs in Scala 2,
+  This means that `Mirror.Sum` differs in this respect from Shapeless's generic representation for ADTs in Scala 2,
   where the constructors are ordered alphabetically by name.
 + The methods `ordinal` and `fromProduct` are defined in terms of `MirroredMonoType` which is the type of kind-`*`
   which is obtained from `MirroredType` by wildcarding its type parameters.
@@ -159,7 +159,7 @@ Type class authors will most likely use higher level derivation or generic progr
 described above and Scala 3's general metaprogramming features is provided below. It is not anticipated that type class
 authors would normally implement a `derived` method in this way, however this walkthrough can be taken as a guide for
 authors of the higher level derivation libraries that we expect typical type class authors will use (for a fully
-worked out example of such a library, see [shapeless 3](https://github.com/milessabin/shapeless/tree/shapeless-3)).
+worked out example of such a library, see [Shapeless 3](https://github.com/milessabin/shapeless/tree/shapeless-3)).
 
 #### How to write a type class `derived` method using low level mechanisms
 
@@ -307,7 +307,7 @@ Alternative approaches can be taken to the way that `derived` methods can be def
 inlined variants using Scala 3 macros, whilst being more involved for type class authors to write than the example
 above, can produce code for type classes like `Eq` which eliminate all the abstraction artefacts (eg. the `Lists` of
 child instances in the above) and generate code which is indistinguishable from what a programmer might write by hand.
-As a third example, using a higher level library such as shapeless the type class author could define an equivalent
+As a third example, using a higher level library such as Shapeless the type class author could define an equivalent
 `derived` method as,
 
 ```scala
@@ -317,9 +317,12 @@ given eqSum[A](using inst: => K0.CoproductInstances[Eq, A]): Eq[A] with
 
 given eqProduct[A](using inst: K0.ProductInstances[Eq, A]): Eq[A] with
    def eqv(x: A, y: A): Boolean = inst.foldLeft2(x, y)(true: Boolean)(
-      [t] => (acc: Boolean, eqt: Eq[t], t0: t, t1: t) => Complete(!eqt.eqv(t0, t1))(false)(true)
+      [t] => (acc: Boolean, eqt: Eq[t], t0: t, t1: t) =>
+         Complete(!eqt.eqv(t0, t1))(false)(true)
+   )
 
-inline def derived[A](using gen: K0.Generic[A]) as Eq[A] = gen.derive(eqSum, eqProduct)
+inline def derived[A](using gen: K0.Generic[A]) as Eq[A] =
+   gen.derive(eqSum, eqProduct)
 ```
 
 The framework described here enables all three of these approaches without mandating any of them.
@@ -385,6 +388,6 @@ written these casts will never fail.
 As mentioned, however, the compiler-provided mechanism is intentionally very low level and it is anticipated that
 higher level type class derivation and generic programming libraries will build on this and Scala 3's other
 metaprogramming facilities to hide these low-level details from type class authors and general users. Type class
-derivation in the style of both shapeless and Magnolia are possible (a prototype of shapeless 3, which combines
-aspects of both shapeless 2 and Magnolia has been developed alongside this language feature) as is a more aggressively
+derivation in the style of both Shapeless and Magnolia are possible (a prototype of Shapeless 3, which combines
+aspects of both Shapeless 2 and Magnolia has been developed alongside this language feature) as is a more aggressively
 inlined style, supported by Scala 3's new quote/splice macro and inlining facilities.

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

@@ -80,6 +80,7 @@ import Instances.{im, given Ordering[?]}
 ```
 
 would import `im`, `intOrd`, and `listOrd` but leave out `ec`.
+
 ### Migration
 
 The rules for imports stated above have the consequence that a library

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](https://doc.rust-lang.org/rust-by-example/trait.html) or [Swift's protocol extensions](https://docs.swift.org/swift-book/LanguageGuide/Protocols.html#ID521). 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](https://agda.readthedocs.io/en/latest/language/implicit-arguments.html).
+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](https://coq.inria.fr/refman/language/extensions/implicit-arguments.html) 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.
 
@@ -30,12 +30,14 @@ Particular criticisms are:
  3. The syntax of implicit definitions is too minimal. It consists of a single modifier, `implicit`, that can be attached to a large number of language constructs. A problem with this for newcomers is that it conveys mechanism instead of intent. For instance, a type class instance is an implicit object or val if unconditional and an implicit def with implicit parameters referring to some class if conditional. This describes precisely what the implicit definitions translate to -- just drop the `implicit` modifier, and that's it! But the cues that define intent are rather indirect and can be easily misread, as demonstrated by the definitions of `i1` and `i2` above.
 
  4. The syntax of implicit parameters also has shortcomings. While implicit _parameters_ are designated specifically, arguments are not. Passing an argument to an implicit parameter looks like a regular application `f(arg)`. This is problematic because it means there can be confusion regarding what parameter gets instantiated in a call. For instance, in
+
     ```scala
     def currentMap(implicit ctx: Context): Map[String, Int]
     ```
-    one cannot write `currentMap("abc")` since the string "abc" is taken as explicit argument to the implicit `ctx` parameter. One has to write `currentMap.apply("abc")` instead, which is awkward and irregular. For the same reason, a method definition can only have one implicit parameter section and it must always come last. This restriction not only reduces orthogonality, but also prevents some useful program constructs, such as a method with a regular parameter whose type depends on an implicit value. Finally, it's also a bit annoying that implicit parameters must have a name, even though in many cases that name is never referenced.
 
- 5. Implicits pose challenges for tooling. The set of available implicits depends on context, so command completion has to take context into account. This is feasible in an IDE but docs like ScalaDoc that are based static web pages can only provide an approximation. Another problem is that failed implicit searches often give very unspecific error messages, in particular if some deeply recursive implicit search has failed. Note that the Scala 3 compiler has already made a lot of progress in the error diagnostics area. If a recursive search fails some levels down, it shows what was constructed and what is missing. Also, it suggests imports that can bring missing implicits in scope.
+    one cannot write `currentMap("abc")` since the string `"abc"` is taken as explicit argument to the implicit `ctx` parameter. One has to write `currentMap.apply("abc")` instead, which is awkward and irregular. For the same reason, a method definition can only have one implicit parameter section and it must always come last. This restriction not only reduces orthogonality, but also prevents some useful program constructs, such as a method with a regular parameter whose type depends on an implicit value. Finally, it's also a bit annoying that implicit parameters must have a name, even though in many cases that name is never referenced.
+
+ 5. Implicits pose challenges for tooling. The set of available implicits depends on context, so command completion has to take context into account. This is feasible in an IDE but tools like [Scaladoc](https://docs.scala-lang.org/overviews/scaladoc/overview.html) that are based on static web pages can only provide an approximation. Another problem is that failed implicit searches often give very unspecific error messages, in particular if some deeply recursive implicit search has failed. Note that the Scala 3 compiler has already made a lot of progress in the error diagnostics area. If a recursive search fails some levels down, it shows what was constructed and what is missing. Also, it suggests imports that can bring missing implicits in scope.
 
 None of the shortcomings is fatal, after all implicits are very widely used, and many libraries and applications rely on them. But together, they make code using implicits a lot more cumbersome and less clear than it could be.
 

docs/docs/reference/contextual/multiversal-equality.md

@@ -96,7 +96,8 @@ class Box[T](x: T) derives CanEqual
 By the usual rules of [type class derivation](./derivation.md),
 this generates the following `CanEqual` instance in the companion object of `Box`:
 ```scala
-given [T, U](using CanEqual[T, U]): CanEqual[Box[T], Box[U]] = CanEqual.derived
+given [T, U](using CanEqual[T, U]): CanEqual[Box[T], Box[U]] =
+   CanEqual.derived
 ```
 That is, two boxes are comparable with `==` or `!=` if their elements are. Examples:
 ```scala

docs/docs/reference/contextual/relationship-implicits.md

@@ -95,7 +95,7 @@ mirroring the definition syntax. E.g, `max(2, 3)(using IntOrd)`.
 Scala 2 uses normal applications `max(2, 3)(IntOrd)` instead. The Scala 2 syntax has some inherent ambiguities and restrictions which are overcome by the new syntax. For instance, multiple implicit parameter lists are not available in the old syntax, even though they can be simulated using auxiliary objects in the "Aux" pattern.
 
 The `summon` method corresponds to `implicitly` in Scala 2.
-It is precisely the same as the `the` method in Shapeless.
+It is precisely the same as the `the` method in [Shapeless](https://github.com/milessabin/shapeless).
 The difference between `summon` (or `the`) and `implicitly` is
 that `summon` can return a more precise type than the type that was
 asked for.
@@ -129,7 +129,7 @@ Abstract extension methods in traits that are implemented in given instances hav
 
 ### Type Class Derivation
 
-Type class derivation has no direct counterpart in the Scala 2 language. Comparable functionality can be achieved by macro-based libraries such as Shapeless, Magnolia, or scalaz-deriving.
+Type class derivation has no direct counterpart in the Scala 2 language. Comparable functionality can be achieved by macro-based libraries such as [Shapeless](https://github.com/milessabin/shapeless), [Magnolia](https://propensive.com/opensource/magnolia), or [scalaz-deriving](https://github.com/scalaz/scalaz-deriving).
 
 ### Context Function Types
 

docs/docs/reference/enums/desugarEnums.md

@@ -25,7 +25,7 @@ some terminology and notational conventions:
 
 The desugaring rules imply that class cases are mapped to case classes, and singleton cases are mapped to `val` definitions.
 
-There are nine desugaring rules. Rule (1) desugar enum definitions. Rules
+There are nine desugaring rules. Rule (1) desugars enum definitions. Rules
 (2) and (3) desugar simple cases. Rules (4) to (6) define `extends` clauses for cases that
 are missing them. Rules (7) to (9) define how such cases with `extends` clauses
 map into `case class`es or `val`s.
@@ -176,10 +176,11 @@ If `E` contains at least one simple case, its companion object will define in ad
      follows.
 
      ```scala
-     private def $new(_$ordinal: Int, $name: String) = new E with runtime.EnumValue:
-        def ordinal = _$ordinal
-        override def productPrefix = $name // if not overridden in `E`
-        override def toString = $name      // if not overridden in `E`
+     private def $new(_$ordinal: Int, $name: String) =
+        new E with runtime.EnumValue:
+           def ordinal = _$ordinal
+           override def productPrefix = $name // if not overridden in `E`
+           override def toString = $name      // if not overridden in `E`
      ```
 
 The anonymous class also implements the abstract `Product` methods that it inherits from `Enum`.

docs/docs/reference/enums/enums.md

@@ -44,7 +44,7 @@ The companion object of an enum also defines three utility methods.
 The `valueOf` method obtains an enum value
 by its name. The `values` method returns all enum values
 defined in an enumeration in an `Array`. The `fromOrdinal`
-method obtains an enum value from its ordinal (Int) value.
+method obtains an enum value from its ordinal (`Int`) value.
 
 ```scala
 scala> Color.valueOf("Blue")
@@ -63,7 +63,7 @@ It is possible to add your own definitions to an enum. Example:
 enum Planet(mass: Double, radius: Double):
    private final val G = 6.67300E-11
    def surfaceGravity = G * mass / (radius * radius)
-   def surfaceWeight(otherMass: Double) =  otherMass * surfaceGravity
+   def surfaceWeight(otherMass: Double) = otherMass * surfaceGravity
 
    case Mercury extends Planet(3.303e+23, 2.4397e6)
    case Venus   extends Planet(4.869e+24, 6.0518e6)
@@ -72,7 +72,7 @@ enum Planet(mass: Double, radius: Double):
    case Jupiter extends Planet(1.9e+27,   7.1492e7)
    case Saturn  extends Planet(5.688e+26, 6.0268e7)
    case Uranus  extends Planet(8.686e+25, 2.5559e7)
-  case Neptune extends Planet(1.024e+26, 2.4746e7)
+   case Neptune extends Planet(1.024e+26, 2.4746e7)
 end Planet
 ```
 

docs/docs/reference/features-classification.md

@@ -162,7 +162,7 @@ Being new features, existing code migrates without changes. To be sure, sometime
 
 ## Metaprogramming
 
-The following constructs together aim to put metaprogramming in Scala on a new basis. So far, metaprogramming was achieved by a combination of macros and libraries such as Shapeless that were in turn based on some key macros. Current Scala 2 macro mechanisms are a thin veneer on top the current Scala 2 compiler, which makes them fragile and in many cases impossible to port to Scala 3.
+The following constructs together aim to put metaprogramming in Scala on a new basis. So far, metaprogramming was achieved by a combination of macros and libraries such as [Shapeless](https://github.com/milessabin/shapeless) that were in turn based on some key macros. Current Scala 2 macro mechanisms are a thin veneer on top the current Scala 2 compiler, which makes them fragile and in many cases impossible to port to Scala 3.
 
 It's worth noting that macros were never included in the Scala 2 language specification and were so far made available only under an `-experimental` flag. This has not prevented their widespread usage.
 

docs/docs/reference/metaprogramming/erased-terms-spec.md

@@ -3,8 +3,6 @@ layout: doc-page
 title: "Erased Terms Spec"
 ---
 
-# Implementation
-
 ## Rules
 
 1. The `erased` modifier can appear: