Updates to contextual/* docs

Author: odersky

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

@@ -5,11 +5,11 @@ title: "Context Bounds"
 
 ## Context Bounds
 
-A context bound is a shorthand for expressing a common pattern of an inferable 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 a 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 inferable parameter `given Ord[T]`. The inferable 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 `given 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
 ```

docs/docs/reference/contextual/conversions.md

@@ -14,7 +14,7 @@ implied for Conversion[String, Token] {
   def apply(str: String): Token = new KeyWord(str)
 }
 ```
-Using an implied alias this can be expressed more concisely as:
+Using an implied alias instance this can be expressed more concisely as:
 ```scala
 implied for Conversion[String, Token] = new KeyWord(_)
 ```
@@ -25,7 +25,7 @@ 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 in the implied scope for a an instance of
+In the first case, the compiler looks for an implied instance of
 `scala.Conversion` that maps an argument of type `T` to type `S`. In the second and third
 case, it looks for an instance of `scala.Conversion` that maps an argument of type `T`
 to a type that defines a member `m` which can be applied to `args` if present.
@@ -59,9 +59,9 @@ object Completions {
     //
     //   CompletionArg.fromStatusCode(statusCode)
 
-    implied fromString for Conversion[String, CompletionArg] = Error(_)
-    implied fromFuture for Conversion[Future[HttpResponse], CompletionArg] = Response(_)
-    implied fromStatusCode for Conversion[Future[StatusCode], CompletionArg] = Status(_)
+    implied fromString     for Conversion[String, CompletionArg]               = Error(_)
+    implied fromFuture     for Conversion[Future[HttpResponse], CompletionArg] = Response(_)
+    implied fromStatusCode for Conversion[Future[StatusCode], CompletionArg]   = Status(_)
   }
   import CompletionArg._
 

docs/docs/reference/contextual/derivation.md

@@ -3,7 +3,7 @@ layout: doc-page
 title: Typeclass Derivation
 ---
 
-Typeclass derivation is a way to generate instances of certain type classes automatically or with minimal code hints. A type class in this sense is any trait or class with a type parameter that describes the type being operated on. Commonly used examples are `Eql`, `Ordering`, `Show`, or `Pickling`. Example:
+Typeclass derivation is a way to generate implied instances of certain type classes automatically or with minimal code hints. A type class in this sense is any trait or class with a type parameter that describes the type being operated on. Commonly used examples are `Eql`, `Ordering`, `Show`, or `Pickling`. Example:
 ```scala
 enum Tree[T] derives Eql, Ordering, Pickling {
   case Branch(left: Tree[T], right: Tree[T])
@@ -12,14 +12,14 @@ enum Tree[T] derives Eql, Ordering, Pickling {
 ```
 The `derives` clause generates implied instances of the `Eql`, `Ordering`, and `Pickling` traits in the companion object `Tree`:
 ```scala
-implied [T: Eql]       for Eql[Tree[T]]       = Eql.derived
-implied [T: Ordering]  for Ordering[Tree[T]] = Ordering.derived
-implied [T: Pickling]  for Pickling[Tree[T]] = Pickling.derived
+implied [T: Eql]      for Eql[Tree[T]]       = Eql.derived
+implied [T: Ordering] for Ordering[Tree[T]] = Ordering.derived
+implied [T: Pickling] for 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.
@@ -42,7 +42,7 @@ A trait or class can appear in a `derives` clause if its companion object define
 ```scala
   def derived[T] given Generic[T] = ...
 ```
-That is, the `derived` method takes an inferable parameter of type `Generic` that determines the _shape_ of the deriving type `T` and it computes the typeclass implementation according to that shape. An implied `Generic` instance is generated automatically for any type that derives a typeclass with a `derived`
+That is, the `derived` method takes a context parameter of type `Generic` that determines the _shape_ of the deriving type `T` and it computes the typeclass implementation according to that shape. An implied `Generic` instance is generated automatically for any type that derives a typeclass with a `derived`
 method that refers to `Generic`. One can also derive `Generic` alone, which means a `Generic` instance is generated without any other type class instances. E.g.:
 ```scala
 sealed trait ParseResult[T] derives Generic
@@ -142,15 +142,15 @@ abstract class Generic[T] {
 ```
 It defines the `Shape` type for the ADT `T`, as well as two methods that map between a
 type `T` and a generic representation of `T`, which we call a `Mirror`:
-The `reflect` method maps an instance value of the ADT `T` to its mirror whereas
+The `reflect` method maps an instance of the ADT `T` to its mirror whereas
 the `reify` method goes the other way. There's also a `common` method that returns
 a value of type `GenericClass` which contains information that is the same for all
 instances of a class (right now, this consists of the runtime `Class` value and
 the names of the cases and their parameters).
 
 ### Mirrors
 
-A mirror is a generic representation of an instance value of an ADT. `Mirror` objects have three components:
+A mirror is a generic representation of an instance of an ADT. `Mirror` objects have three components:
 
  - `adtClass: GenericClass`: The representation of the ADT class
  - `ordinal: Int`: The ordinal number of the case among all cases of the ADT, starting from 0
@@ -208,15 +208,15 @@ a mirror over that array, and finally uses the `reify` method in `Reflected` to
 
 ### How to Write Generic Typeclasses
 
-Based on the machinery developed so far it becomes possible to define type classes generically. This means that the `derived` method will compute a type class instance for any ADT that has a `Generic` instance, recursively.
+Based on the machinery developed so far it becomes possible to define type classes generically. This means that the `derived` method will compute a type class instance for any ADT that has an implied `Generic` instance, recursively.
 The implementation of these methods typically uses three new type-level constructs in Dotty: inline methods, inline matches, and implicit matches. As an example, here is one possible implementation of a generic `Eql` type class, with explanations. Let's assume `Eql` is defined by the following trait:
 ```scala
 trait Eql[T] {
   def eql(x: T, y: T): Boolean
 }
 ```
-We need to implement a method `Eql.derived` that produces an instance of `Eql[T]` provided
-there exists evidence of type `Generic[T]`. Here's a possible solution:
+We need to implement a method `Eql.derived` that produces an instance for `Eql[T]` provided
+there exists an implied instance for `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 = {
@@ -307,15 +307,15 @@ The last, and in a sense most interesting part of the derivation is the comparis
   }
 ```
 `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 an implied instance of `Eql[T]`. If an instance `ev` is found, it proceeds by comparing the arguments using `ev.eql`. On the other hand, if no instance is found
-this signals a compilation error: the user tried a generic derivation of `Eql` for a class with an element type that does not support an `Eql` instance itself. The error is signaled by
+this signals a compilation error: the user tried a generic derivation of `Eql` for a class with an element type that does not have an `Eql` instance itself. The error is signaled by
 calling the `error` method defined in `scala.compiletime`.
 
 **Note:** At the moment our error diagnostics for metaprogramming does not support yet interpolated string arguments for the `scala.compiletime.error` method that is called in the second case above. As an alternative, one can simply leave off the second case, then a missing typeclass would result in a "failure to reduce match" error.
 
 **Example:** Here is a slightly polished and compacted version of the code that's generated by inline expansion for the derived `Eql` instance of class `Tree`.
 
 ```scala
-implied [T] given (elemEq: Eql[T]) for Eql[Tree[T]] {
+implied [T] for Eql[Tree[T]] given (elemEq: Eql[T]) {
   def eql(x: Tree[T], y: Tree[T]): Boolean = {
     val ev = the[Generic[Tree[T]]]
     val mx = ev.reflect(x)
@@ -336,14 +336,14 @@ implied [T] given (elemEq: Eql[T]) for Eql[Tree[T]] {
 
 One important difference between this approach and Scala-2 typeclass derivation frameworks such as Shapeless or Magnolia is that no automatic attempt is made to generate typeclass instances of elements recursively using the generic derivation framework. There must be an implied instance of `Eql[T]` (which can of course be produced in turn using `Eql.derived`), or the compilation will fail. The advantage of this more restrictive approach to typeclass derivation is that it avoids uncontrolled transitive typeclass derivation by design. This keeps code sizes smaller, compile times lower, and is generally more predictable.
 
-### Derived Instances Elsewhere
+### Deriving Instances Elsewhere
 
 Sometimes one would like to derive a typeclass instance for an ADT after the ADT is defined, without being able to change the code of the ADT itself.
 To do this, simply define an instance with the `derived` method of the typeclass as right-hand side. E.g, to implement `Ordering` for `Option`, define:
 ```scala
-implied [T: Ordering]: Ordering[Option[T]] = Ordering.derived
+implied [T: Ordering] for Ordering[Option[T]] = Ordering.derived
 ```
-Usually, the `Ordering.derived` clause has an inferable parameter of type
+Usually, the `Ordering.derived` clause has a context parameter of type
 `Generic[Option[T]]`. Since the `Option` trait has a `derives` clause,
 the necessary implied instance is already present in the companion object of `Option`.
 If the ADT in question does not have a `derives` clause, an implied `Generic` instance

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

@@ -90,11 +90,11 @@ implied StringOps {
   }
 }
 
-implied ListOps {
+implied {
   def (xs: List[T]) second[T] = xs.tail.head
 }
 ```
-If such implied instances are anonymous (as in the examples above), their name is synthesized from the name
+If such a representative is anonymous (as in the second clause above), its name is synthesized from the name
 of the first defined extension method.
 
 ### Operators
@@ -144,7 +144,3 @@ to the [current syntax](https://github.com/lampepfl/dotty/blob/master/docs/docs/
 DefSig            ::=  ...
                     |  ‘(’ DefParam ‘)’ [nl] id [DefTypeParamClause] DefParamClauses
 ```
-
-
-
-

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

@@ -1,6 +1,6 @@
 ---
 layout: doc-page
-title: "Implied Imports"
+title: "Importing Implied Instances"
 ---
 
 A special form of import is used to import implied instances. Example:
@@ -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 implied instance `tc`. Conversely, the second import `import implied A._` will import _only_ that implied instance.
 
-Generally, a normal import clause brings all definitions except implied instances into scope whereas an `import implied` clause brings only implied instances into scope.
+Generally, a normal import clause brings all members except implied instances into scope whereas an `import implied` clause brings only implied instances into scope.
 
 There are two main benefits arising from these rules:
 
@@ -28,22 +28,22 @@ There are two main benefits arising from these rules:
    instances can be anonymous, so the usual recourse of using named imports is not
    practical.
 
-### Relationship with Old-Style Implicits
+### Migration
 
-The rules of implied imports above have the consequence that a library
+The rules for `import implied` above have the consequence that a library
 would have to migrate in lockstep with all its users from old style implicits and
 normal imports to implied instances and imports.
 
 The following modifications avoid this hurdle to migration.
 
- 1. An implied import also brings old style implicits into scope. So, in Scala 3.0
-    an old-style implicit definition can be brought into scope either by a normal or
-    by an implied import.
+ 1. An `import implied` also brings old style implicits into scope. So, in Scala 3.0
+    an old-style implicit definition can be brought into scope either by a normal import or
+    by an `import implied`.
 
- 2. In Scala 3.1, an old-style implicits accessed implicitly through a normal import
+ 2. In Scala 3.1, old-style implicits accessed through a normal import
     will give a deprecation warning.
 
- 3. In some version after 3.1, an old-style implicits accessed implicitly through a normal import
+ 3. In some version after 3.1, an old-style implicit accessed through a normal import
     will give a compiler error.
 
 These rules mean that library users can use `import implied` to access old-style implicits in Scala 3.0,

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

@@ -1,9 +1,9 @@
 ---
 layout: doc-page
-title: "Inferable By-Name Parameters"
+title: "By-Name Context Parameters"
 ---
 
-Inferable by-name parameters can be used to avoid a divergent inferred expansion. Example:
+Context parameters can be declared by-name to avoid a divergent inferred expansion. Example:
 
 ```scala
 trait Codec[T] {
@@ -12,7 +12,7 @@ trait Codec[T] {
 
 implied intCodec for Codec[Int] = ???
 
-implied optionCodec[T] given (ev: => Codec[T]) for Codec[Option[T]] {
+implied optionCodec[T] for Codec[Option[T]] given (ev: => Codec[T]) {
   def write(xo: Option[T]) = xo match {
     case Some(x) => ev.write(x)
     case None =>
@@ -24,14 +24,14 @@ val s = the[Codec[Option[Int]]]
 s.write(Some(33))
 s.write(None)
 ```
-As is the case for a normal by-name parameter, the argument for the inferable parameter `ev`
+As is the case for a normal by-name parameter, the argument for the context parameter `ev`
 is evaluated on demand. In the example above, if the option value `x` is `None`, it is
 not evaluated at all.
 
-The synthesized argument for an inferable parameter is backed by a local val
+The synthesized argument for a context parameter is backed by a local val
 if this is necessary to prevent an otherwise diverging expansion.
 
-The precise steps for constructing an inferable argument for a by-name parameter of type `=> T` are as follows.
+The precise steps for synthesizing an argument for a by-name context parameter of type `=> T` are as follows.
 
  1. Create a new implied instance of type `T`: