rebased with upstream

Author: michelou

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

@@ -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