Tweaks to wordings in docs

Also: drop some doc pages that are no longer used.

Author: odersky

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

@@ -9,16 +9,16 @@ A context bound is a shorthand for expressing a common pattern of an inferable p
 ```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 inferred parameter `given Ord[T]`. The inferred 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 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.,
+```scala
 def f[T: C1 : C2, U: C3](x: T) given (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
 ```
 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 = ...
 ```
 

docs/docs/reference/contextual/conversions.md

@@ -1,20 +1,20 @@
 ---
 layout: doc-page
-title: "Implied Conversions"
+title: "Inferable Conversions"
 ---
 
 Inferable conversions are defined by implied instances of the `scala.Conversion` class.
 This class is defined in package `scala` as follows:
 ```scala
 abstract class Conversion[-T, +U] extends (T => U)
 ```
-For example, here is an implied conversion from `String` to `Token`:
+For example, here is an inferable conversion from `String` to `Token`:
 ```scala
 implied for Conversion[String, Token] {
   def apply(str: String): Token = new KeyWord(str)
 }
 ```
-An implied conversion is applied automatically by the compiler in three situations:
+An inferable conversion is applied automatically by the compiler in three situations:
 
 1. If an expression `e` has type `T`, and `T` does not conform to the expression's expected type `S`.
 2. In a selection `e.m` with `e` of type `T`, but `T` defines no member `m`.

docs/docs/reference/contextual/derivation.md

@@ -47,8 +47,8 @@ These two conditions ensure that the synthesized derived instances for the trait
 ```scala
   def derived[T] with 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. A `Generic` instance is generated automatically
-for any types that derives a typeclass that needs it. One can also derive `Generic` alone, which means a `Generic` instance is generated without any other type class instances. E.g.:
+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`
+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
 ```
@@ -97,7 +97,7 @@ Cases[(
 Note that an empty element tuple is represented as type `Unit`. A single-element tuple
 is represented as `T *: Unit` since there is no direct syntax for such tuples: `(T)` is just `T` in parentheses, not a tuple.
 
-### The Generic TypeClass
+### 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 implied instance of `Generic[C[T_1,...,T_n]]` that follows
 the outline below:

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

@@ -78,39 +78,39 @@ and where `T` is the expected type. The following two rewritings are tried in or
 So `circle.circumference` translates to `CircleOps.circumference(circle)`, provided
 `circle` has type `Circle` and `CircleOps` is an eligible implied instance (i.e. it is visible at the point of call or it is defined in the companion object of `Circle`).
 
-## Instances for Extension Methods
+### Implied Instances for Extension Methods
 
-Instances that define extension methods can also be defined without an `of` clause. E.g.,
+Implied instances that define extension methods can also be defined without an `of` clause. E.g.,
 
 ```scala
-instance StringOps {
+implied StringOps {
   def (xs: Seq[String]) longestStrings: Seq[String] = {
     val maxLength = xs.map(_.length).max
     xs.filter(_.length == maxLength)
   }
 }
 
-instance ListOps {
+implied ListOps {
   def (xs: List[T]) second[T] = xs.tail.head
 }
 ```
-If such instances are anonymous (as in the examples above), their name is synthesized from the name
+If such implied instances are anonymous (as in the examples above), their name is synthesized from the name
 of the first defined extension method.
 
 ### 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
   def (x: String) < (y: String) = ...
   def (x: Elem) +: (xs: Seq[Elem]) = ...
 
   "ab" + "c"
   1 +: List(2, 3)
 ```
 The two definitions above translate to
-```
+```scala
   def < (x: String)(y: String) = ...
   def +: (xs: Seq[Elem])(x: Elem) = ...
 ```
@@ -120,23 +120,17 @@ to the implementation of right binding operators as normal methods.
 
 ### Generic Extensions
 
-The `StringSeqOps` examples extended a specific instance of a generic type. It is also possible to extend a generic type by adding type parameters to an extension method:
+The `StringSeqOps` examples extended a specific instance of a generic type. It is also possible to extend a generic type by adding type parameters to an extension method. Examples:
 
 ```scala
-def (xs: List[T]) second [T] = xs.tail.head
-```
-
-or:
+def (xs: List[T]) second [T] =
+  xs.tail.head
 
+def (xs: List[List[T]]) flattened [T] =
+  xs.foldLeft[List[T]](Nil)(_ ++ _)
 
-```scala
-def (xs: List[List[T]]) flattened [T] = xs.foldLeft[List[T]](Nil)(_ ++ _)
-```
-
-or:
-
-```scala
-def (x: T) + [T : Numeric](y: T): T = implicitly[Numeric[T]].plus(x, y)
+def (x: T) + [T : Numeric](y: T): T =
+  implicitly[Numeric[T]].plus(x, y)
 ```
 
 As usual, type parameters of the extension method follow the defined method name. Nevertheless, such type parameters can already be used in the preceding parameter clause.

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

@@ -3,7 +3,7 @@ layout: doc-page
 title: "Inferable By-Name Parameters"
 ---
 
-Call-by-name inferable parameters can be used to avoid a divergent inferred expansion.
+Inferable by-name parameters can be used to avoid a divergent inferred expansion. Example:
 
 ```scala
 trait Codec[T] {
@@ -36,16 +36,17 @@ The precise steps for constructing an inferable argument for a by-name parameter
  1. Create a new implied instance of type `T`:
 
     ```scala
-    implied for T = ???
+    implied lv for T = ???
     ```
+    where `lv` is an arbitrary fresh name.
 
- 1. This instance is not immediately available as candidate for argument inference (making it immediately available would result in a loop in the synthesized computation). But it becomes available in all nested contexts that look again for an inferred argument to a by-name parameter.
+ 1. This instance 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 inferred argument to a by-name parameter.
 
- 1. If this search succeeds with expression `E`, and `E` contains references to the implied instance created previously, replace `E` by
+ 1. If this search succeeds with expression `E`, and `E` contains references to the implied instance `lv`, replace `E` by
 
 
     ```scala
-    { implied for T = E; lv }
+    { implied lv for T = E; lv }
     ```
 
     Otherwise, return `E` unchanged.

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

@@ -94,7 +94,7 @@ The `infer` method is simply defined as the identity function over an inferable
 ```scala
 def infer[T] given (x: T) = x
 ```
-Functions like `infer` that have only inferable parameters are also called implicit _queries_.
+Functions like `infer` that have only inferable parameters are also called _context queries_.
 
 ## Syntax
 

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

@@ -1,23 +1,21 @@
 ---
 layout: doc-page
-title: "Query Types - More Details"
+title: "Context Query Types - More Details"
 ---
 
-Initial implementation in (#1775)[https://github.com/lampepfl/dotty/pull/1775].
-
 ## Syntax
 
     Type              ::=  ...
                         |  `given' FunArgTypes `=>' Type
     Expr              ::=  ...
                         |  `given' FunParams `=>' Expr
 
-Query types associate to the right, e.g.
+Context query types associate to the right, e.g.
 `given S => given T => U` is the same as `given S => (given T => U)`.
 
 ## Implementation
 
-Query types are shorthands for class types that define `apply`
+Context query types are shorthands for class types that define `apply`
 methods with inferable parameters. Specifically, the `N`-ary function type
 `T1, ..., TN => R` is a shorthand for the class type
 `ImplicitFunctionN[T1 , ... , TN, R]`. Such class types are assumed to have the following definitions, for any value of `N >= 1`:
@@ -27,10 +25,10 @@ trait ImplicitFunctionN[-T1 , ... , -TN, +R] {
   def apply given (x1: T1 , ... , xN: TN): R
 }
 ```
-Query types erase to normal function types, so these classes are
+Context query types erase to normal function types, so these classes are
 generated on the fly for typechecking, but not realized in actual code.
 
-Query literals `given (x1: T1, ..., xn: Tn) => e` map
+Context query literals `given (x1: T1, ..., xn: Tn) => e` map
 inferable parameters `xi` of types `Ti` to a result given by expression `e`.
 The scope of each implicit parameter `xi` is `e`. The parameters must have pairwise distinct names.
 
@@ -55,18 +53,17 @@ abbreviated to `given x => e`.
 An inferable parameter may also be a wildcard represented by an underscore `_`. In
 that case, a fresh name for the parameter is chosen arbitrarily.
 
-Note: The closing paragraph of the [Anonymous Functions section](https://www
-.scala-lang.org/files/archive/spec/2.12/06-expressions.html#anonymous-
-functions) of the Scala 2.12 is subsumed by query types and should
-be removed.
+Note: The closing paragraph of the
+[Anonymous Functions section](https://www.scala-lang.org/files/archive/spec/2.12/06-expressions.html#anonymous-functions)
+of Scala 2.12 is subsumed by query types and should be removed.
 
 Query literals `given (x1: T1, ..., xn: Tn) => e` are
 automatically created for any expression `e` whose expected type is
 `scala.ImplicitFunctionN[T1, ..., Tn, R]`, unless `e` is
 itself a query literal. This is analogous to the automatic
 insertion of `scala.Function0` around expressions in by-name argument position.
 
-Query types generalize to `N > 22` in the same way that function types do, see [the corresponding
+Context query types generalize to `N > 22` in the same way that function types do, see [the corresponding
 documentation](https://dotty.epfl.ch/docs/reference/dropped-features/limit22.html).
 
 ## Examples
@@ -79,4 +76,4 @@ Gist](https://gist.github.com/OlivierBlanvillain/234d3927fe9e9c6fba074b53a7bd9
 
 ### Type Checking
 
-After desugaring no additional typing rules are required for query types.
+After desugaring no additional typing rules are required for context query types.

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

@@ -1,14 +1,15 @@
 ---
 layout: doc-page
-title: "First Class Queries"
+title: "Context Queries"
 ---
 
-In the context of inference, _queries_ are functions with inferable parameters.
-_Query types_ are the types of first-class queries. Example:
+_Context queries_ are functions with inferable parameters.
+_Context query types_ are the types of first-class context queries.
+Here is an example for a context query type:
 ```scala
 type Contextual[T] = given Context => T
 ```
-A value of query type is applied to inferred arguments, in
+A value of context query type is applied to inferred arguments, in
 the same way a method with inferable parameters is applied. For instance:
 ```scala
   implied ctx for Context = ...
@@ -18,9 +19,9 @@ the same way a method with inferable parameters is applied. For instance:
   f(2) given ctx   // explicit argument
   f(2)             // argument is inferred
 ```
-Conversely, if the expected type of an expression `E` is a query
+Conversely, if the expected type of an expression `E` is a context query
 type `given (T_1, ..., T_n) => U` and `E` is not already a
-query literal, `E` is converted to a query literal by rewriting to
+context query literal, `E` is converted to a context query literal by rewriting to
 ```scala
   given (x_1: T1, ..., x_n: Tn) => E
 ```
@@ -31,7 +32,7 @@ are available as implied instances in `E`.
 Like query types, query literals are written with a `given` prefix. They differ from normal function literals in two ways:
 
  1. Their parameters are inferable.
- 2. Their types are query types.
+ 2. Their types are context query types.
 
 For example, continuing with the previous definitions,
 ```scala
@@ -45,7 +46,7 @@ For example, continuing with the previous definitions,
 ```
 ### Example: Builder Pattern
 
-Query types have considerable expressive power. For
+Context query types have considerable expressive power. For
 instance, here is how they can support the "builder pattern", where
 the aim is to construct tables like this:
 ```scala
@@ -111,7 +112,7 @@ With that setup, the table construction code above compiles and expands to:
 ```
 ### Example: Postconditions
 
-As a larger example, here is a way to define constructs for checking arbitrary postconditions using `ensuring` so that the checked result can be referred to simply by `result`. The example combines opaque aliases, query 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 `ensuring` so that the checked result can be referred to simply by `result`. The example combines opaque aliases, context query types, and extension methods to provide a zero-overhead abstraction.
 
 ```scala
 object PostConditions {
@@ -136,7 +137,7 @@ object Test {
   val s = List(1, 2, 3).sum.ensuring(result == 6)
 }
 ```
-**Explanations**: We use a query type `given WrappedResult[T] => Boolean`
+**Explanations**: We use a context query type `given WrappedResult[T] => Boolean`
 as the type of the condition of `ensuring`. An argument to `ensuring` such as
 `(result == 6)` will therefore have an implied instance of type `WrappedResult[T]` in
 scope to pass along to the `result` method. `WrappedResult` is a fresh type, to make sure