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/implicit-conversions.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

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

@@ -6,7 +6,7 @@ title: Relationship with Scala 2 Implicits"
 Many, but not all, of the new contextual abstraction features in Scala 3 can be mapped to Scala 2's implicits.
 This page gives a rundown on the relationships between new and old features.
 
-# Simulating Contextual Abstraction with Implicits
+## Simulating Contextual Abstraction with Implicits
 
 ### Implied Instance Definitions
 
@@ -109,7 +109,7 @@ Implicit function types have no analogue in Scala 2.
 
 Implicit by-name parameters are not supported in Scala 2, but can be emulated to some degree by the `Lazy` type in Shapeless.
 
-# Simulating Scala 2 in Dotty
+## Simulating Scala 2 in Dotty
 
 ### Implicit Conversions
 

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

@@ -3,11 +3,11 @@ layout: doc-page
 title: Dropped: Limit 22
 ---
 
-The limit of 22 for the maximal number of parameters of function types
-has been dropped.  Functions can now have an arbitrary number of
+The limits of 22 for the maximal number of parameters of function types
+and the maximal number of fields in tuple types have been dropped.
+
+Functions can now have an arbitrary number of
 parameters. Functions beyond Function22 are represented with a new trait
 `scala.FunctionXXL`.
 
-The limit of 22 for the size of tuples is about to be dropped. Tuples
-will in the future be represented by an HList-like structure which can
-be arbitrarily large.
+Tuples can also have an arbitrary number of fields. Furthermore, they support generic operation such as concatenation and indexing.

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

@@ -52,7 +52,7 @@ sidebar:
               url: docs/reference/contextual/typeclasses.html
             - title: Typeclass Derivation
               url: docs/reference/derivation.html
-            - title: Query Types
+            - title: Context Queries
               url: docs/reference/contextual/query-types.html
             - title: Implied Conversions
               url: docs/reference/contextual/conversions.html