Fixes to repr and implicit trials

Author: odersky

docs/docs/reference/contextual-implicit/inferable-by-name-parameters.md

@@ -40,7 +40,7 @@ The precise steps for synthesizing an argument for a by-name parameter of type `
     ```
     where `lv` is an arbitrary fresh name.
 
- 1. This implicit is not immediately available as candidate for argument inference (making it immediately available could result in a loop in the synthesized computation). But it becomes available in all nested contexts that look again for an implicit argument to a by-name parameter.
+ 1. This implicit is not immediately available as a candidate for argument inference (making it immediately available could result in a loop in the synthesized computation). But it becomes available in all nested contexts that look again for an implicit argument to a by-name parameter.
 
  1. If this search succeeds with expression `E`, and `E` contains references to the implicit `lv`, replace `E` by
 

docs/docs/reference/contextual-implicit/inferable-params.md

@@ -30,7 +30,7 @@ max(List(1, 2, 3), Nil)
 
 ## Anonymous Implicit Parameters
 
-In many situations, the name of an implicit parameter of a method need not be mentioned explicitly at all, since it is only used as synthesized implicit for other constraints. In that case one can avoid defining a parameter name and just provide its type. Example:
+In many situations, the name of an implicit parameter of a method need not be mentioned explicitly at all, since it is only used as a synthesized argument for other implicit parameters. In that case one can avoid defining a parameter name and just provide its type. Example:
 ```scala
 def maximum[T](xs: List[T]) given Ord[T]: T =
   xs.reduceLeft(max)

docs/docs/reference/contextual-implicit/instance-defs.md

@@ -41,14 +41,14 @@ The name of an implicit instance can be left out. So the implicit instance defin
 of the last section can also be expressed like this:
 ```scala
 implicit for Ord[Int] { ... }
-implicit [T]  or Ord[List[T]] given (ord: Ord[T]) { ... }
+implicit [T] for Ord[List[T]] given (ord: Ord[T]) { ... }
 ```
 If the name of an implicit is missing, the compiler will synthesize a name from
 the type(s) in the `for` clause.
 
 ## Alias Implicits
 
-An alias implicit defines an implicit value that is equal to some expression. E.g.:
+An alias can be used to define an implicit value that is equal to some expression. E.g.:
 ```scala
 implicit global for ExecutionContext = new ForkJoinPool()
 ```

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

@@ -31,7 +31,7 @@ that derives `Eql`, e.g.
 ```scala
 class T derives Eql
 ```
-Alternatively, one can also provide an `Eql` implicit directly, like this:
+Alternatively, one can also define an `Eql` implicit directly, like this:
 ```scala
 implicit for Eql[T, T] = Eql.derived
 ```
@@ -141,7 +141,7 @@ The `Eql` object defines implicits for comparing
  - `java.lang.Number`, `java.lang.Boolean`, and `java.lang.Character`,
  - `scala.collection.Seq`, and `scala.collection.Set`.
 
-Implicits are defined so that every one of these types is has a reflexive `Eql` implicit, and the following holds:
+Implicits are defined so that every one of these types has a reflexive `Eql` implicit, and the following holds:
 
  - Primitive numeric types can be compared with each other.
  - Primitive numeric types can be compared with subtypes of `java.lang.Number` (and _vice versa_).

docs/docs/reference/contextual-implicit/query-types-spec.md

@@ -76,4 +76,4 @@ Gist](https://gist.github.com/OlivierBlanvillain/234d3927fe9e9c6fba074b53a7bd9
 
 ### Type Checking
 
-After desugaring no additional typing rules are required for context query types.
+After desugaring no additional typing rules are required for implicit function types.

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

@@ -140,11 +140,11 @@ one can write
 
 ### Implicit Classes
 
-Implicit classes in Scala 2 are often used to define extension methods, which are directly supported in Dotty. Other uses of implicit classes can be simulated by a pair of a regular class and a conversion delegate.
+Implicit classes in Scala 2 are often used to define extension methods, which are directly supported in Dotty. Other uses of implicit classes can be simulated by a pair of a regular class and a conversion instance.
 
 ### Abstract Implicits
 
-An abstract implicit `val` or `def` in Scala 2 can be expressed in Dotty using a regular abstract definition and an implicit alias. E.g., Scala 2's
+An abstract implicit `val` or `def` in Scala 2 can be expressed in Dotty using a regular abstract definition and an alias implicit. E.g., Scala 2's
 ```scala
   implicit def symDeco: SymDeco
 ```

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

@@ -10,7 +10,7 @@ enum Tree[T] derives Eql, Ordering, Pickling {
   case Leaf(elem: T)
 }
 ```
-The `derives` clause generates repr representatives of the `Eql`, `Ordering`, and `Pickling` traits in the companion object `Tree`:
+The `derives` clause generates representatives of the `Eql`, `Ordering`, and `Pickling` traits in the companion object `Tree`:
 ```scala
 repr [T: Eql]      of Eql[Tree[T]]       = Eql.derived
 repr [T: Ordering] of Ordering[Tree[T]] = Ordering.derived
@@ -19,7 +19,7 @@ repr [T: Pickling] of Pickling[Tree[T]] = Pickling.derived
 
 ### Deriving Types
 
-Besides for `enums`, typeclasses can also be derived for other sets of classes and objects that form an algebraic data type. These are:
+Besides for enums, typeclasses can also be derived for other sets of classes and objects that form an algebraic data type. These are:
 
  - individual case classes or case objects
  - sealed classes or traits that have only case classes and case objects as children.
@@ -93,8 +93,7 @@ is represented as `T *: Unit` since there is no direct syntax for such tuples: `
 
 ### The Generic Typeclass
 
-For every class `C[T_1,...,T_n]` with a `derives` clause, the compiler generates in the companion object of `C` an representative of `Generic[C[T_1,...,T_n]]` that follows
-the outline below:
+For every class `C[T_1,...,T_n]` with a `derives` clause, the compiler generates in the companion object of `C` a representative of `Generic[C[T_1,...,T_n]]` that follows the outline below:
 ```scala
 repr [T_1, ..., T_n] of Generic[C[T_1,...,T_n]] {
   type Shape = ...
@@ -215,7 +214,7 @@ trait Eql[T] {
 }
 ```
 We need to implement a method `Eql.derived` that produces a representative of `Eql[T]` provided
-there exists evidence of type `Generic[T]`. Here's a possible solution:
+there exists a representative of type `Generic[T]`. Here's a possible solution:
 ```scala
   inline def derived[T] given (ev: Generic[T]): Eql[T] = new Eql[T] {
     def eql(x: T, y: T): Boolean = {
@@ -234,7 +233,7 @@ there exists evidence of type `Generic[T]`. Here's a possible solution:
 The implementation of the inline method `derived` creates a representative of `Eql[T]` and implements its `eql` method. The right-hand side of `eql` mixes compile-time and runtime elements. In the code above, runtime elements are marked with a number in parentheses, i.e
 `(1)`, `(2)`, `(3)`. Compile-time calls that expand to runtime code are marked with a number in brackets, i.e. `[4]`, `[5]`. The implementation of `eql` consists of the following steps.
 
-  1. Map the compared values `x` and `y` to their mirrors using the `reflect` method of the implicitly passed `Generic` evidence `(1)`, `(2)`.
+  1. Map the compared values `x` and `y` to their mirrors using the `reflect` method of the implicitly passed `Generic` `(1)`, `(2)`.
   2. Match at compile-time against the shape of the ADT given in `ev.Shape`. Dotty does not have a construct for matching types directly, but we can emulate it using an `inline` match over an `erasedValue`. Depending on the actual type `ev.Shape`, the match will reduce at compile time to one of its two alternatives.
   3. If `ev.Shape` is of the form `Cases[alts]` for some tuple `alts` of alternative types, the equality test consists of comparing the ordinal values of the two mirrors `(3)` and, if they are equal, comparing the elements of the case indicated by that ordinal value. That second step is performed by code that results from the compile-time expansion of the `eqlCases` call `[4]`.
   4. If `ev.Shape` is of the form `Case[elems]` for some tuple `elems` for element types, the elements of the case are compared by code that results from the compile-time expansion of the `eqlElems` call `[5]`.
@@ -302,7 +301,7 @@ The last, and in a sense most interesting part of the derivation is the comparis
     case ev: Eql[T] =>
       ev.eql(x, y)                              // (15)
     case _ =>
-      error("No `Eql` representative was found for $T")
+      error("No `Eql` instance was found for $T")
   }
 ```
 `tryEql` is an inline method that takes an element type `T` and two element values of that type as arguments. It is defined using an `implicit match` that tries to find a representative of `Eql[T]`. If a representative `ev` is found, it proceeds by comparing the arguments using `ev.eql`. On the other hand, if no representative is found

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

@@ -56,7 +56,7 @@ Then
 ```scala
 List("here", "is", "a", "list").longestStrings
 ```
-is legal everywhere `ops1` is available as a representative. Alternatively, we can define `longestStrings` as a member of a normal object. But then the method has to be brought into scope to be usable as an extension method.
+is legal everywhere `ops1` is eligible. Alternatively, we can define `longestStrings` as a member of a normal object. But then the method has to be brought into scope to be usable as an extension method.
 
 ```scala
 object ops2 extends StringSeqOps
@@ -80,7 +80,7 @@ So `circle.circumference` translates to `CircleOps.circumference(circle)`, provi
 
 ### Representatives for Extension Methods
 
-Representatives that define extension methods can also be defined without a `for` clause. E.g.,
+Representatives that define extension methods can also be defined without an `of` clause. E.g.,
 
 ```scala
 repr StringOps {
@@ -94,12 +94,12 @@ repr {
   def (xs: List[T]) second[T] = xs.tail.head
 }
 ```
-If such representatives are anonymous (as in the second clause), their name is synthesized from the name
+If such a representative is anonymous (as in the second clause), its name is synthesized from the name
 of the first defined extension method.
 
 ### Operators
 
-The extension method syntax also applies to the definitions of operators.
+The extension method syntax also applies to the definition of operators.
 In each case the definition syntax mirrors the way the operator is applied.
 Examples:
 ```scala

docs/docs/reference/contextual-repr/import-implied.md

@@ -18,7 +18,7 @@ object B {
 In the code above, the `import A._` clause of object `B` will import all members
 of `A` _except_ the representative `tc`. Conversely, the second import `import repr A._` will import _only_ that representative.
 
-Generally, a normal import clause brings all definitions except representatives into scope whereas an `import repr` clause brings only representatives into scope.
+Generally, a normal import clause brings all members except representatives into scope whereas an `import repr` clause brings only representatives into scope.
 
 There are two main benefits arising from these rules:
 
@@ -29,7 +29,7 @@ There are two main benefits arising from these rules:
    can be anonymous, so the usual recourse of using named imports is not
    practical.
 
-### Relationship with Old-Style Implicits
+### Migration
 
 The rules of representatives above have the consequence that a library
 would have to migrate in lockstep with all its users from old style implicits and
@@ -49,4 +49,4 @@ The following modifications avoid this hurdle to migration.
 
 These rules mean that library users can use `import repr` to access old-style implicits in Scala 3.0,
 and will be gently nudged and then forced to do so in later versions. Libraries can then switch to
-representation clauses once their user base has migrated.
+`repr` clauses once their user base has migrated.

docs/docs/reference/contextual-repr/inferable-by-name-parameters.md

@@ -40,7 +40,7 @@ The precise steps for synthesizing an argument for a by-name parameter of type `
     ```
     where `lv` is an arbitrary fresh name.
 
- 1. This representative is not immediately available as candidate for argument inference (making it immediately available could result in a loop in the synthesized computation). But it becomes available in all nested contexts that look again for an argument to an implicit by-name parameter.
+ 1. This representative is not immediately eligible as a candidate for argument inference (making it immediately eligible could result in a loop in the synthesized computation). But it becomes eligible in all nested contexts that look again for an implicit argument to a by-name parameter.
 
  1. If this search succeeds with expression `E`, and `E` contains references to the representative `lv`, replace `E` by