Polishings

Author: odersky

docs/docs/reference/contextual/conversions.md

@@ -14,7 +14,7 @@ given as Conversion[String, Token] {
   def apply(str: String): Token = new KeyWord(str)
 }
 ```
-Using an alias given this can be expressed more concisely as:
+Using an alias this can be expressed more concisely as:
 ```scala
 given as Conversion[String, Token] = new KeyWord(_)
 ```

docs/docs/reference/contextual/delegates.md

@@ -87,5 +87,5 @@ SimpleConstrApp  ::=  AnnotType {ArgumentExprs}
 GivenParamClause ::=  ‘given’ (‘(’ [DefParams] ‘)’ | GivenTypes)
 GivenTypes       ::=  AnnotType {‘,’ AnnotType}
 ```
-The identifier `id` can be omitted only if either the `for` part or the template body is present.
-If the `for` part is missing, the template body must define at least one extension method.
+The identifier `id` can be omitted only if either the `as` part or the template body is present.
+If the `as` part is missing, the template body must define at least one extension method.

docs/docs/reference/contextual/derivation.md

@@ -34,16 +34,16 @@ case class Some[T] extends Option[T]
 case object None extends Option[Nothing]
 ```
 
-The generated typeclass delegates are placed in the companion objects `Labelled` and `Option`, respectively.
+The generated typeclass instances are placed in the companion objects `Labelled` and `Option`, respectively.
 
 ### Derivable Types
 
 A trait or class can appear in a `derives` clause if its companion object defines a method named `derived`. The type and implementation of a `derived` method are arbitrary, but typically it has a definition like this:
 ```scala
-  def derived[T] where Mirror.Of[T] = ...
+  def derived[T] given Mirror.Of[T] = ...
 ```
 That is, the `derived` method takes an implicit parameter of (some subtype of) type `Mirror` that defines the shape of the deriving type `T` and it computes the typeclass implementation according
-to that shape. A `Mirror` delegate is generated automatically for
+to that shape. A given `Mirror` instance is generated automatically for
 
  - case classes and objects,
  - enums and enum cases,

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

@@ -36,7 +36,7 @@ When is an extension method applicable? There are two possibilities.
 
  - An extension method is applicable if it is visible under a simple name, by being defined
    or inherited or imported in a scope enclosing the application.
- - An extension method is applicable if it is a member of some instance that is given at the point of the application.
+ - An extension method is applicable if it is a member of some given instance at the point of the application.
 
 As an example, consider an extension method `longestStrings` on `String` defined in a trait `StringSeqOps`.
 
@@ -48,15 +48,15 @@ trait StringSeqOps {
   }
 }
 ```
-We can make the extension method available by defining a given of class `StringSeqOps`, like this:
+We can make the extension method available by defining a given `StringSeqOps` instance, like this:
 ```scala
 given ops1 as StringSeqOps
 ```
 Then
 ```scala
 List("here", "is", "a", "list").longestStrings
 ```
-is legal everywhere `ops1` is available as a given instance. 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 available. 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
@@ -76,7 +76,7 @@ and where `T` is the expected type. The following two rewritings are tried in or
     from `T` to a type containing `m`. If there is more than one way of rewriting, an ambiguity error results.
 
 So `circle.circumference` translates to `CircleOps.circumference(circle)`, provided
-`circle` has type `Circle` and `CircleOps` is a given instance (i.e. it is visible at the point of call or it is defined in the companion object of `Circle`).
+`circle` has type `Circle` and `CircleOps` is given  (i.e. it is visible at the point of call or it is defined in the companion object of `Circle`).
 
 ### Given Instances for Extension Methods
 

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

@@ -1,6 +1,6 @@
 ---
 layout: doc-page
-title: "Given Clauses"
+title: "Given Parameters"
 ---
 
 Functional programming tends to express most dependencies as simple function parameterization.

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

@@ -55,7 +55,8 @@ In the example above, the definition of `s` would be expanded as follows.
 
 ```scala
 val s = the[Test.Codec[Option[Int]]](
-  optionCodec[Int](intCodec))
+  optionCodec[Int](intCodec)
+)
 ```
 
 No local given instance was generated because the synthesized argument is not recursive.

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

@@ -29,7 +29,7 @@ Implicit function types erase to normal function types, so these classes are
 generated on the fly for typechecking, but not realized in actual code.
 
 Implicit function literals `given (x1: T1, ..., xn: Tn) => e` map
-implicit parameters `xi` of types `Ti` to the result of evaluating expression `e`.
+implicit parameters `xi` of types `Ti` to the result of evaluating the expression `e`.
 The scope of each implicit parameter `xi` is `e`. The parameters must have pairwise distinct names.
 
 If the expected type of the implicit function literal is of the form
@@ -42,7 +42,7 @@ type of `e`. `T` must be equivalent to a type which does not refer to any of
 the implicit parameters `xi`.
 
 The implicit function literal is evaluated as the instance creation
-expression:
+expression
 ```scala
 new scala.ImplicitFunctionN[T1, ..., Tn, T] {
   def apply given (x1: T1, ..., xn: Tn): T = e

docs/docs/reference/contextual/implicit-function-types.md

@@ -19,8 +19,6 @@ the same way a method with a given clause is applied. For instance:
   f(2) given ec    // explicit argument
   f(2)             // argument is inferred
 ```
-def foo[T](x: T, y: T) given Ord[T], {x < y}: ....
-
 Conversely, if the expected type of an expression `E` is an implicit function type
 `given (T_1, ..., T_n) => U` and `E` is not already an
 implicit function literal, `E` is converted to an implicit function literal by rewriting to
@@ -29,7 +27,7 @@ implicit function literal, `E` is converted to an implicit function literal by r
 ```
 where the names `x_1`, ..., `x_n` are arbitrary. This expansion is performed
 before the expression `E` is typechecked, which means that `x_1`, ..., `x_n`
-are given instances in `E`.
+are available as givens in `E`.
 
 Like their types, implicit function literals are written with a `given` prefix. They differ from normal function literals in two ways:
 
@@ -42,7 +40,7 @@ For example, continuing with the previous definitions,
 
   g(22)      // is expanded to g(given ev => 22)
 
-  g(f(2))    // is expanded to g(given ev => f(2) given ev)
+  g(f(2))    // is expanded to g(given ev => (f(2) given ev))
 
   g(given ctx => f(22) given ctx) // is left as it is
 ```
@@ -90,31 +88,31 @@ that would otherwise be necessary.
     t
   }
 
-  def row(init: given Row => Unit) where (t: Table) = {
+  def row(init: given Row => Unit) given (t: Table) = {
     given r as Row
     init
     t.add(r)
   }
 
-  def cell(str: String) where (r: Row) =
+  def cell(str: String) given (r: Row) =
     r.add(new Cell(str))
 ```
 With that setup, the table construction code above compiles and expands to:
 ```scala
   table { given ($t: Table) =>
     row { given ($r: Row) =>
-      cell("top left") where $r
-      cell("top right") where $r
-    } where $t
+      cell("top left") given $r
+      cell("top right") given $r
+    } given $t
     row { given ($r: Row) =>
-      cell("bottom left") where $r
-      cell("bottom right") where $r
-    } where $t
+      cell("bottom left") given $r
+      cell("bottom right") given $r
+    } given $t
   }
 ```
 ### Example: Postconditions
 
-As a larger example, here is a way to define constructs for checking arbitrary postconditions using an extension method `ensuring`so that the checked result can be referred to simply by `result`. The example combines opaque aliases, implicit function types, and extension methods to provide a zero-overhead abstraction.
+As a larger example, here is a way to define constructs for checking arbitrary postconditions using an extension method `ensuring` so that the checked result can be referred to simply by `result`. The example combines opaque aliases, implicit function types, and extension methods to provide a zero-overhead abstraction.
 
 ```scala
 object PostConditions {
@@ -123,7 +121,7 @@ object PostConditions {
   def result[T] given (r: WrappedResult[T]): T = r
 
   def (x: T)
-      ensuring [T] (condition: given WrappedResult[T] => Boolean): T =
+      ensuring[T](condition: given WrappedResult[T] => Boolean): T =
     assert(condition) given x
 }
 import PostConditions.{ensuring, result}

docs/docs/reference/contextual/import-delegate.md

@@ -36,7 +36,12 @@ Since givens can be anonymous it is not always practical to import them by their
 ```scala
 import given A.{_: TC}
 ```
-This imports any given in `A` that has a type which conforms to `TC`. There can be several bounding types following a `_ :` and bounding types can contain wildcards.
+This imports any given in `A` that has a type which conforms to `TC`. Importing givens of several types `T1,...,Tn`
+is expressed by bounding with a union type.
+```
+import given A.{_: T1 | ... | Tn}
+```
+Importing all instances of a parameterized if expressed by wildcard arguments.
 For instance, assuming the object
 ```scala
 object Instances {
@@ -48,15 +53,15 @@ object Instances {
 ```
 the import
 ```scala
-import given Instances.{_: Ordering[_] | ExecutionContext}
+import given Instances.{_: Ordering[?] | ExecutionContext}
 ```
 would import the `intOrd`, `listOrd`, and `ec` instances but leave out the `im` instance, since it fits none of the specified bounds.
 
 By-type imports can be mixed with by-name imports. If both are present in an import clause, by-type imports come last. For instance, the import clause
 ```scala
-import given Instances.{im, _: Ordering[_]}
+import given Instances.{im, _: Ordering[?]}
 ```
-would import `im`, `intOrd`, and `listOrd` but leave out `ec`. By-type imports cannot be mixed with a wildcard import in the same import clause.
+would import `im`, `intOrd`, and `listOrd` but leave out `ec`.
 
 Bounded wildcard selectors also work for normal imports and exports. For instance, consider the following `enum` definition:
 ```scala

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

@@ -75,7 +75,7 @@ get their name from the name of the first extension method and the toplevel type
 constructor of its first parameter. For example, the given instance
 ```scala
   given {
-     def (xs: List[T]) second[T] = ...
+    def (xs: List[T]) second[T] = ...
   }
 ```
 gets the synthesized name `second_of_List_T_given`.