Merge pull request #8189 from dotty-staging/update-dcos

Update docs to 0.22RC

Author: anatoliykmetyuk

docs/docs/reference/contextual/context-bounds-new.md

@@ -3,29 +3,36 @@ layout: doc-page
 title: "Context Bounds"
 ---
 
-**Note** The syntax described in this section is currently under revision.
-[Here is the new version which will be implemented in Dotty 0.22](./context-bounds-new.html).
-
 ## Context Bounds
 
-A context bound is a shorthand for expressing the common pattern of an implicit parameter that depends on a type parameter. Using a context bound, the `maximum` function of the last section can be written like this:
+A context bound is a shorthand for expressing the common pattern of a context parameter that depends on a type parameter. Using a context bound, the `maximum` function of the last section can be written like this:
 ```scala
 def maximum[T: Ord](xs: List[T]): T = xs.reduceLeft(max)
 ```
-A bound like `: Ord` on a type parameter `T` of a method or class indicates an implicit parameter `(given Ord[T])`. The implicit parameter(s) generated from context bounds come last in the definition of the containing method or class. E.g.,
+A bound like `: Ord` on a type parameter `T` of a method or class indicates a context parameter `with Ord[T]`. The context parameter(s) generated from context bounds come last in the definition of the containing method or class. E.g.,
 ```scala
-def f[T: C1 : C2, U: C3](x: T)(given y: U, z: V): R
+def f[T: C1 : C2, U: C3](x: T)(using y: U, z: V): R
 ```
 would expand to
 ```scala
-def f[T, U](x: T)(given y: U, z: V)(given C1[T], C2[T], C3[U]): R
+def f[T, U](x: T)(using y: U, z: V)(using C1[T], C2[T], C3[U]): R
 ```
 Context bounds can be combined with subtype bounds. If both are present, subtype bounds come first, e.g.
 ```scala
 def g[T <: B : C](x: T): R = ...
 ```
 
-## Syntax
+### Migration
+
+To ease migration, context bounds in Dotty map in Scala 3.0 to old-style implicit parameters
+for which arguments can be passed either with a `(using ...)` clause or with a normal application. From Scala 3.1 on, they will map to context parameters instead, as is described above.
+
+If the source version is `3.1` and the `-migration` command-line option is set, any pairing of an evidence
+context parameter stemming from a context bound with a normal argument will give a migration
+warning. The warning indicates that a `(using ...)` clause is needed instead. The rewrite can be
+done automatically under `-rewrite`.
+
+### Syntax
 
 ```
 TypeParamBounds   ::=  [SubtypeBounds] {ContextBound}

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

@@ -3,9 +3,6 @@ layout: doc-page
 title: "Implicit Conversions"
 ---
 
-**Note** The syntax described in this section is currently under revision.
-[Here is the new version which will be implemented in Dotty 0.22](./conversions-new.html).
-
 Implicit conversions are defined by given instances of the `scala.Conversion` class.
 This class is defined in package `scala` as follows:
 ```scala
@@ -28,19 +25,19 @@ An implicit conversion is applied automatically by the compiler in three situati
 3. In an application `e.m(args)` with `e` of type `T`, if `T` does define
    some member(s) named `m`, but none of these members can be applied to the arguments `args`.
 
-In the first case, the compiler looks for a given `scala.Conversion` that maps
+In the first case, the compiler looks for a given `scala.Conversion` instance that maps
 an argument of type `T` to type `S`. In the second and third
-case, it looks for a given `scala.Conversion` that maps an argument of type `T`
+case, it looks for a given `scala.Conversion` instance that maps an argument of type `T`
 to a type that defines a member `m` which can be applied to `args` if present.
-If such an instance `C` is given, the expression `e` is replaced by `C.apply(e)`.
+If such an instance `C` is found, the expression `e` is replaced by `C.apply(e)`.
 
 ## Examples
 
 1. The `Predef` package contains "auto-boxing" conversions that map
 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: Conversion[Int, java.lang.Integer] =
+given int2Integer as Conversion[Int, java.lang.Integer] =
  java.lang.Integer.valueOf(_)
 ```
 
@@ -62,9 +59,9 @@ object Completions {
     //
     //   CompletionArg.fromStatusCode(statusCode)
 
-    given fromString     : Conversion[String, CompletionArg]               = Error(_)
-    given fromFuture     : Conversion[Future[HttpResponse], CompletionArg] = Response(_)
-    given fromStatusCode : Conversion[Future[StatusCode], CompletionArg]   = Status(_)
+    given fromString     as Conversion[String, CompletionArg]               = Error(_)
+    given fromFuture     as Conversion[Future[HttpResponse], CompletionArg] = Response(_)
+    given fromStatusCode as Conversion[Future[StatusCode], CompletionArg]   = Status(_)
   }
   import CompletionArg._
 

docs/docs/reference/contextual/conversions-new.md

@@ -3,87 +3,4 @@ layout: doc-page
 title: "Given Instances"
 ---
 
-**Note** The syntax described in this section is currently under revision.
-[Here is the new version which will be implemented in Dotty 0.22](./givens.html).
-
-Given instances (or, simply, "givens") define "canonical" values of certain types
-that serve for synthesizing arguments to [given clauses](./given-clauses.md). Example:
-
-```scala
-trait Ord[T] {
-  def compare(x: T, y: T): Int
-  def (x: T) < (y: T) = compare(x, y) < 0
-  def (x: T) > (y: T) = compare(x, y) > 0
-}
-
-given intOrd: Ord[Int] {
-  def compare(x: Int, y: Int) =
-    if (x < y) -1 else if (x > y) +1 else 0
-}
-
-given listOrd[T](given ord: Ord[T]): Ord[List[T]] {
-
-  def compare(xs: List[T], ys: List[T]): Int = (xs, ys) match {
-    case (Nil, Nil) => 0
-    case (Nil, _) => -1
-    case (_, Nil) => +1
-    case (x :: xs1, y :: ys1) =>
-      val fst = ord.compare(x, y)
-      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
-for `Ord[List[T]]` for all types `T` that come with a given instance for `Ord[T]` themselves.
-The `(given ord: Ord[T])` clause in `listOrd` defines an implicit parameter.
-Given clauses are further explained in the [next section](./given-clauses.md).
-
-## Anonymous Given Instances
-
-The name of a given instance can be left out. So the definitions
-of the last section can also be expressed like this:
-```scala
-given Ord[Int] { ... }
-given [T](given Ord[T]): Ord[List[T]] { ... }
-```
-If the name of a given is missing, the compiler will synthesize a name from
-the implemented type(s).
-
-## Alias Givens
-
-An alias can be used to define a given instance that is equal to some expression. E.g.:
-```scala
-given global: ExecutionContext = new ForkJoinPool()
-```
-This creates a given `global` of type `ExecutionContext` that resolves to the right
-hand side `new ForkJoinPool()`.
-The first time `global` is accessed, a new `ForkJoinPool` is created, which is then
-returned for this and all subsequent accesses to `global`.
-
-Alias givens can be anonymous, e.g.
-```scala
-given Position = enclosingTree.position
-given (given outer: Context): Context = outer.withOwner(currentOwner)
-```
-An alias given can have type parameters and given clauses just like any other given instance, but it can only implement a single type.
-
-## Given Instance Initialization
-
-A given instance without type parameters or given clause is initialized on-demand, the first
-time it is accessed.
-If a `given` definition has type parameters or a given clause, a fresh instance is created for each reference.
-
-## Syntax
-
-Here is the new syntax of given instances, seen as a delta from the [standard context free syntax of Scala 3](../../internals/syntax.md).
-```
-TmplDef          ::=  ...
-                  |   ‘given’ GivenDef
-GivenDef         ::=  [GivenSig (‘:’ | <:)] Type ‘=’ Expr
-                  |   [GivenSig ‘:’] [ConstrApp {‘,’ ConstrApp }] [TemplateBody]
-GivenSig         ::=  [id] [DefTypeParamClause] {GivenParamClause}
-GivenParamClause ::=  ‘(’ ‘given’ (DefParams | GivenTypes) ‘)’
-GivenTypes       ::=  Type {‘,’ Type}
-```
-The identifier `id` can be omitted only if some types are implemented or the template body defines at least one extension method.
+The contents of this page have [moved](./givens.html).