Update docs

Author: odersky

community-build/community-projects/dotty-cps-async

@@ -10,9 +10,9 @@ trait Codec[T] {
   def write(x: T): Unit
 }
 
-given intCodec as Codec[Int] = ???
+given Codec[Int] as intCodec = ???
 
-given optionCodec[T](using ev: => Codec[T]) as Codec[Option[T]] {
+given [T] => (ev: => Codec[T]) => Codec[Option[T]] as optionCodec {
   def write(xo: Option[T]) = xo match {
     case Some(x) => ev.write(x)
     case None =>
@@ -36,7 +36,7 @@ The precise steps for synthesizing an argument for a by-name context parameter o
  1. Create a new given of type `T`:
 
     ```scala
-    given lv as T = ???
+    given T as lv = ???
     ```
     where `lv` is an arbitrary fresh name.
 
@@ -46,7 +46,7 @@ The precise steps for synthesizing an argument for a by-name context parameter o
 
 
     ```scala
-    { given lv as T = E; lv }
+    { given T as lv = E; lv }
     ```
 
     Otherwise, return `E` unchanged.

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

@@ -13,7 +13,7 @@ Context functions are written using `?=>` as the "arrow" sign.
 They are applied to synthesized arguments, in
 the same way methods with context parameters are applied. For instance:
 ```scala
-  given ec as ExecutionContext = ...
+  given ExecutionContext as ec = ...
 
   def f(x: Int): ExecutionContext ?=> Int = ...
 
@@ -86,13 +86,13 @@ with context function types as parameters to avoid the plumbing boilerplate
 that would otherwise be necessary.
 ```scala
   def table(init: Table ?=> Unit) = {
-    given t as Table // note the use of a creator application; same as: given t as Table = new Table
+    given Table as t // note the use of a creator application; same as: given t as Table = new Table
     init
     t
   }
 
   def row(init: Row ?=> Unit)(using t: Table) = {
-    given r as Row
+    given Row as r
     init
     t.add(r)
   }

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

@@ -37,7 +37,7 @@ If such an instance `C` is found, the expression `e` is replaced by `C.apply(e)`
 primitive number types to subclasses of `java.lang.Number`. For instance, the
 conversion from `Int` to `java.lang.Integer` can be defined as follows:
 ```scala
-given int2Integer as Conversion[Int, java.lang.Integer] =
+given Conversion[Int, java.lang.Integer] as int2Integer =
  java.lang.Integer.valueOf(_)
 ```
 
@@ -59,9 +59,9 @@ object Completions {
     //
     //   CompletionArg.fromStatusCode(statusCode)
 
-    given fromString     as Conversion[String, CompletionArg]               = Error(_)
-    given fromFuture     as Conversion[Future[HttpResponse], CompletionArg] = Response(_)
-    given fromStatusCode as Conversion[Future[StatusCode], CompletionArg]   = Status(_)
+    given Conversion[String, CompletionArg]               as fromString     = Error(_)
+    given Conversion[Future[HttpResponse], CompletionArg] as fromFuture     = Response(_)
+    given Conversion[Future[StatusCode], CompletionArg]   as fromStatusCode = Status(_)
   }
   import CompletionArg._
 

docs/docs/reference/contextual/conversions.md

@@ -25,13 +25,13 @@ we need to implement a method `Eq.derived` on the companion object of `Eq` that
 produces a quoted instance for `Eq[T]`. Here is a possible signature,
 
 ```scala
-given derived[T: Type](using Quotes) as Expr[Eq[T]]
+given [T: Type] => Quotes => Expr[Eq[T]] as derived
 ```
 
 and for comparison reasons we give the same signature we had with `inline`:
 
 ```scala
-inline given derived[T] as (m: Mirror.Of[T]) => Eq[T] = ???
+inline given [T] => (m: Mirror.Of[T]) => Eq[T] as derived = ???
 ```
 
 Note, that since a type is used in a subsequent stage it will need to be lifted
@@ -176,7 +176,7 @@ object Eq {
     case '[EmptyTuple] => Nil
   }
 
-  given derived[T: Type](using q: Quotes) as Expr[Eq[T]] = {
+  given [T: Type] => (q: Quotes) => Expr[Eq[T]] as derived = {
     import quotes.reflect._
 
     val ev: Expr[Mirror.Of[T]] = Expr.summon[Mirror.Of[T]].get

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

@@ -19,9 +19,9 @@ The `derives` clause generates the following given instances for the `Eq`, `Orde
 companion object of `Tree`,
 
 ```scala
-given [T: Eq]       as Eq[Tree[T]]    = Eq.derived
-given [T: Ordering] as Ordering[Tree] = Ordering.derived
-given [T: Show]     as Show[Tree]     = Show.derived
+given [T: Eq]       => Eq[Tree[T]]    = Eq.derived
+given [T: Ordering] => Ordering[Tree] = Ordering.derived
+given [T: Show]     => Show[Tree]     = Show.derived
 ```
 
 We say that `Tree` is the _deriving type_ and that the `Eq`, `Ordering` and `Show` instances are _derived instances_.
@@ -179,7 +179,7 @@ we need to implement a method `Eq.derived` on the companion object of `Eq` that
 a `Mirror[T]`. Here is a possible implementation,
 
 ```scala
-inline given derived[T](using m: Mirror.Of[T]) as Eq[T] = {
+inline given derived[T] => (m: Mirror.Of[T]) => Eq[T] = {
   val elemInstances = summonAll[m.MirroredElemTypes]           // (1)
   inline m match {                                             // (2)
     case s: Mirror.SumOf[T]     => eqSum(s, elemInstances)
@@ -278,7 +278,7 @@ object Eq {
         }
     }
 
-  inline given derived[T](using m: Mirror.Of[T]) as Eq[T] = {
+  inline given [T] => (m: Mirror.Of[T]) => Eq[T] as derived = {
     lazy val elemInstances = summonAll[m.MirroredElemTypes]
     inline m match {
       case s: Mirror.SumOf[T]     => eqSum(s, elemInstances)
@@ -309,7 +309,7 @@ In this case the code that is generated by the inline expansion for the derived
 following, after a little polishing,
 
 ```scala
-given derived$Eq[T](using eqT: Eq[T]) as Eq[Opt[T]] =
+given [T] => Eq[T] => Eq[Opt[T]] as derived$Eq =
   eqSum(summon[Mirror[Opt[T]]],
     List(
       eqProduct(summon[Mirror[Sm[T]]], List(summon[Eq[T]]))
@@ -326,19 +326,19 @@ As a third example, using a higher level library such as shapeless the type clas
 `derived` method as,
 
 ```scala
-given eqSum[A](using inst: => K0.CoproductInstances[Eq, A]) as Eq[A] {
+given [A] => (inst: => K0.CoproductInstances[Eq, A]) => Eq[A] as eqSum {
   def eqv(x: A, y: A): Boolean = inst.fold2(x, y)(false)(
     [t] => (eqt: Eq[t], t0: t, t1: t) => eqt.eqv(t0, t1)
   )
 }
 
-given eqProduct[A](using inst: K0.ProductInstances[Eq, A]) as Eq[A] {
+given [A] => (inst: K0.ProductInstances[Eq, A]) => Eq[A] as eqProduct {
   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)
   )
 }
 
-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]): Eq[A] = gen.derive(eqSum, eqProduct)
 ```
 
 The framework described here enables all three of these approaches without mandating any of them.
@@ -354,7 +354,7 @@ change the code of the ADT itself.  To do this, simply define an instance using
 as right-hand side. E.g, to implement `Ordering` for `Option` define,
 
 ```scala
-given [T: Ordering] as Ordering[Option[T]] = Ordering.derived
+given [T: Ordering] => Ordering[Option[T]] = Ordering.derived
 ```
 
 Assuming the `Ordering.derived` method has a context parameter of type `Mirror[T]` it will be satisfied by the

docs/docs/reference/contextual/derivation.md

@@ -194,7 +194,7 @@ trait SafeDiv:
 By the second rule, an extension method can be made available by defining a given instance containing it, like this:
 
 ```scala
-given ops1 as IntOps // brings safeMod into scope
+given IntOps as ops1 // brings safeMod into scope
 
 1.safeMod(2)
 ```
@@ -209,7 +209,7 @@ object List:
   extension [T](xs: List[List[T]])
     def flatten: List[T] = xs.foldLeft(Nil: List[T])(_ ++ _)
 
-  given [T: Ordering] as Ordering[List[T]]:
+  given [T: Ordering] => Ordering[List[T]]:
     extension (xs: List[T])
       def < (ys: List[T]): Boolean = ...
 end List

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

@@ -8,7 +8,7 @@ A special form of import wildcard selector is used to import given instances. Ex
 ```scala
 object A {
   class TC
-  given tc as TC
+  given TC as tc
   def f(using TC) = ???
 }
 
@@ -60,7 +60,7 @@ For instance, assuming the object
 
 ```scala
 object Instances {
-  given intOrd as Ordering[Int]
+  given Ordering[Int] as intOrd
   given listOrd[T: Ordering] as Ordering[List[T]]
   given ec as ExecutionContext = ...
   given im as Monoid[Int]

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

@@ -13,12 +13,12 @@ trait Ord[T] {
   extension (x: T) def > (y: T) = compare(x, y) > 0
 }
 
-given intOrd as Ord[Int] {
+given Ord[Int] {
   def compare(x: Int, y: Int) =
     if (x < y) -1 else if (x > y) +1 else 0
 }
 
-given listOrd[T](using ord: Ord[T]) as Ord[List[T]] {
+given [T] => Ord[T] => Ord[List[T]] {
 
   def compare(xs: List[T], ys: List[T]): Int = (xs, ys) match
     case (Nil, Nil) => 0
@@ -29,41 +29,42 @@ given listOrd[T](using ord: Ord[T]) as Ord[List[T]] {
       if (fst != 0) fst else compare(xs1, ys1)
 }
 ```
-This code defines a trait `Ord` with two given instances. `intOrd` defines
-a given for the type `Ord[Int]` whereas `listOrd[T]` defines givens
+This code defines a trait `Ord` with two given instances. The first instance defines
+a given for the type `Ord[Int]`. The second instance defines givens
 for `Ord[List[T]]` for all types `T` that come with a given instance for `Ord[T]`
-themselves. The `using` clause in `listOrd` defines a condition: There must be a
-given of type `Ord[T]` for a given of type `List[Ord[T]]` to exist.
-Such conditions are expanded by the compiler to [context
-parameters](./using-clauses.html).
+themselves. The parts left to the arrows `=>` are type parameters and conditions.
+In the example above, there must be a given instance of type `Ord[T]` for a given
+instance of type `List[Ord[T]]` to exist. Such conditions are expanded by the compiler
+to [context parameters](./using-clauses.html).
 
-## Anonymous Givens
+## Named Givens
 
-The name of a given can be left out. So the definitions
-of the last section can also be expressed like this:
+One can attach a name to a given instance by following its type with an `as`.
+For instance, the definitions of the last section can be labelled like this:
 ```scala
-given Ord[Int] { ... }
-given [T](using Ord[T]) as Ord[List[T]] { ... }
+given Ord[Int] as intOrd { ... }
+given [T] => Ord[T] => Ord[List[T]] as listOrd { ... }
 ```
 If the name of a given is missing, the compiler will synthesize a name from
 the implemented type(s).
 
-**Note** The name synthesized by the compiler is chosen to be readable and reasonably concise. For instance, the two instances above would get the names:
+**Note** The name synthesized by the compiler is chosen to be readable and
+reasonably concise. For instance, the two instances in the previous section would get the names:
 ```scala
 given_Ord_Int
 given_Ord_List_T
 ```
-The precise rules for synthesizing names are found [here](./relationship-implicits.html#anonymous-given-instances). These rules do not guarantee absence of name conflicts between
-given instances of types that are "too similar". To avoid conflicts one can
-use named instances.
+The precise rules for synthesizing names are found [here](./relationship-implicits.html#anonymous-given-instances).
+These rules do not guarantee absence of name conflicts between given instances of types that
+are "too similar". To avoid conflicts one needs to use named instances.
 
 **Note** To ensure robust binary compatibility, publicly available libraries should prefer named instances.
 
 ## Alias Givens
 
 An alias can be used to define a given instance that is equal to some expression. E.g.:
 ```scala
-given global as ExecutionContext = new ForkJoinPool()
+given ExecutionContext as global = new ForkJoinPool()
 ```
 This creates a given `global` of type `ExecutionContext` that resolves to the right
 hand side `new ForkJoinPool()`.
@@ -73,7 +74,7 @@ returned for this and all subsequent accesses to `global`. This operation is thr
 Alias givens can be anonymous as well, e.g.
 ```scala
 given Position = enclosingTree.position
-given (using config: Config) as Factory = MemoizingFactory(config)
+given (config: Config) => Factory = MemoizingFactory(config)
 ```
 
 An alias given can have type parameters and context parameters just like any other given,
@@ -84,11 +85,11 @@ but it can only implement a single type.
 Given aliases can have the `inline` and `transparent` modifiers.
 Example:
 ```scala
-transparent inline given mkAnnotations[A, T] as Annotations[A, T] = ${
+transparent inline given [A, T] => Annotations[A, T] = ${
   // code producing a value of a subtype of Annotations
 }
 ```
-Since `mkAnnotations` is `transparent`, the type of an application is the type of its right hand side, which can be a proper subtype of the declared result type `Annotations[A, T]`.
+Since the given instance is `transparent`, the type of an application is the type of its right hand side, which can be a proper subtype of the declared result type `Annotations[A, T]`.
 
 ## Pattern-Bound Given Instances
 
@@ -98,7 +99,7 @@ Given instances can also appear as pattern bound-variables. Example:
 for given Context <- applicationContexts do
 
 pair match
-  case (ctx as given Context, y) => ...
+  case (given Context as ctx, y) => ...
 ```
 In the first fragment above, anonymous given instances for class `Context` are established by enumerating over `applicationContexts`. In the second fragment, a given `Context`
 instance named `ctx` is established by matching against the first half of the `pair` selector.
@@ -118,7 +119,8 @@ Here is the new syntax for given instances, seen as a delta from the [standard c
 ```
 TmplDef           ::=  ...
                    |   ‘given’ GivenDef
-GivenDef          ::=  [GivenSig] Type ‘=’ Expr
-                   |   [GivenSig] ConstrApps [TemplateBody]
-GivenSig          ::=  [id] [DefTypeParamClause] {UsingParamClause} ‘as’
+GivenDef          ::=  [GivenParams | `=>`] Type ['as' id] ‘=’ Expr
+                    |  [GivenParams] ConstrApps ['as' id] [TemplateBody]
+GivenParams       ::=  [DefTypeParamClause '=>'] {GivenParamClause '=>'}
+GivenParamClause  ::=  `(` DefParams `)` |  FunArgTypes
 ```

docs/docs/reference/contextual/givens.md

@@ -97,7 +97,7 @@ 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]) as CanEqual[Box[T], Box[U]] = CanEqual.derived
+given [T, U] => CanEqual[T, U] => CanEqual[Box[T], Box[U]] = CanEqual.derived
 ```
 That is, two boxes are comparable with `==` or `!=` if their elements are. Examples:
 ```scala