Docs polishings

docs/_includes/features.html

@@ -21,19 +21,19 @@ <h1 id="so-features">So, features?</h1>
                         <td>Implemented</td>
                     </tr>
                     <tr>
-                        <td><a href="http://dotty.epfl.ch/docs/reference/contextual/query-types.html">Context query</a></td>
+                        <td><a href="http://dotty.epfl.ch/docs/reference/contextual/implicit-function-types.html">Context query</a></td>
                         <td>Implemented</td>
                     </tr>
                     <tr>
                         <td><a href="https://dotty.epfl.ch/docs/reference/other-new-features/trait-parameters.html">Trait parameters</a></td>
                         <td>Implemented</td>
                     </tr>
                     <tr>
-                        <td><a href="https://dotty.epfl.ch/docs/reference/contextual/instance-defs.html">Implied Instances</a></td>
+                        <td><a href="https://dotty.epfl.ch/docs/reference/contextual/delegates.html">Implied Instances</a></td>
                         <td>Implemented</td>
                     </tr>
                     <tr>
-                        <td><a href="https://dotty.epfl.ch/docs/reference/contextual/inferable-params.html">Inferable parameters</a></td>
+                        <td><a href="https://dotty.epfl.ch/docs/reference/contextual/given-clauses.html">Inferable parameters</a></td>
                         <td>Implemented</td>
                     </tr>
                     <tr>

docs/blog/_posts/2019-03-05-13th-dotty-milestone-release.md

@@ -209,7 +209,7 @@ object B {
 ```
 
 **You can read more about** [implied
-imports](https://dotty.epfl.ch/docs/reference/contextual/import-implied.html)
+imports](https://dotty.epfl.ch/docs/reference/contextual/import-delegate.html)
 from the docs or the relevant PR
 [#5868](https://github.com/lampepfl/dotty/pull/5868).
 

docs/blog/_posts/2019-04-15-14th-dotty-milestone-release.md

@@ -124,7 +124,7 @@ For more information, please see the [documentation](http://dotty.epfl.ch/docs/r
 
 Some of the other changes include:
 
-- `infer` method renamed to `the`, the semantics of which is now the same as that of the `the` method of Shapeless. Namely, the implicits are resolved more precisely – see this [gist](https://gist.github.com/milessabin/8833a1dbf7e8245b30f8) for an example in Shapeless, and the Dotty [documentation](http://dotty.epfl.ch/docs/reference/contextual/inferable-params.html#querying-implied-instances) for more details.
+- `infer` method renamed to `the`, the semantics of which is now the same as that of the `the` method of Shapeless. Namely, the implicits are resolved more precisely – see this [gist](https://gist.github.com/milessabin/8833a1dbf7e8245b30f8) for an example in Shapeless, and the Dotty [documentation](http://dotty.epfl.ch/docs/reference/contextual/given-clauses.html#querying-implied-instances) for more details.
 - The syntax of quoting and splicing was changed. Now the quoting is expressed via `'{ ... }` and `'[...]` and splicing – via `${...}` and `$id`. Please see the [documentation](http://dotty.epfl.ch/docs/reference/other-new-features/principled-meta-programming.html) for more details on these features.
 
 # Let us know what you think!

docs/docs/reference/contextual/instance-defs.md → docs/docs/reference/contextual/delegates.md

@@ -4,7 +4,7 @@ title: "Delegates"
 ---
 
 Delegates define "canonical" values of certain types
-that serve for synthesizing arguments to [given clauses](./inferable-params.html). Example:
+that serve for synthesizing arguments to [given clauses](./given-clauses.html). Example:
 
 ```scala
 trait Ord[T] {
@@ -33,7 +33,7 @@ This code defines a trait `Ord` with two delegate definitions. `IntOrd` defines
 a delegate for the type `Ord[Int]` whereas `ListOrd[T]` defines delegates
 for `Ord[List[T]]` for all types `T` that come with a delegate for `Ord[T]` themselves.
 The `given` clause in `ListOrd` defines an implicit parameter.
-Given clauses are further explained in the [next section](./inferable-params.html).
+Given clauses are further explained in the [next section](./given-clauses.html).
 
 ## Anonymous Delegates
 
@@ -59,6 +59,8 @@ returned for this and all subsequent accesses to `global`.
 Alias delegates can be anonymous, e.g.
 ```scala
 delegate for Position = enclosingTree.position
+delegate for Context given (outer: Context) =
+  outer.withOwner(currentOwner)
 ```
 An alias delegate can have type parameters and given clauses just like any other delegate, but it can only implement a single type.
 

docs/docs/reference/contextual/inferable-params.md → docs/docs/reference/contextual/given-clauses.md

@@ -9,7 +9,7 @@ call trees where the same value is passed over and over again in long call chain
 functions. Given clauses can help here since they enable the compiler to synthesize
 repetitive arguments instead of the programmer having to write them explicitly.
 
-For example, given the [delegates](./instance-defs.md) defined previously,
+For example, given the [delegates](./delegates.md) defined previously,
 a maximum function that works for any arguments for which an ordering exists can be defined as follows:
 ```scala
 def max[T](x: T, y: T) given (ord: Ord[T]): T =

docs/docs/reference/contextual/query-types.md → docs/docs/reference/contextual/implicit-function-types.md

@@ -117,19 +117,14 @@ As a larger example, here is a way to define constructs for checking arbitrary p
 object PostConditions {
   opaque type WrappedResult[T] = T
 
-  def result[T] given (r: WrappedResult[T]): T = f
+  def result[T] given (r: WrappedResult[T]): T = r
 
-  def (x: T) ensuring [T](condition: given WrappedResult[T] => Boolean): T = {
-    delegate for WrappedResult[T] = x
-    assert(condition)
-    x
-  }
+  def (x: T) ensuring [T] (condition: given WrappedResult[T] => Boolean): T =
+    assert(condition) given x
 }
+import PostConditions.{ensuring, result}
 
-object Test {
-  import PostConditions.{ensuring, result}
-  val s = List(1, 2, 3).sum.ensuring(result == 6)
-}
+val s = List(1, 2, 3).sum.ensuring(result == 6)
 ```
 **Explanations**: We use an implicit function type `given WrappedResult[T] => Boolean`
 as the type of the condition of `ensuring`. An argument to `ensuring` such as
@@ -151,4 +146,4 @@ as the best possible code one could write by hand:
 For more info, see the [blog article](https://www.scala-lang.org/blog/2016/12/07/implicit-function-types.html),
 (which uses a different syntax that has been superseded).
 
-[More details](./query-types-spec.html)
+[More details](./implicit-function-types-spec.html)

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

@@ -47,13 +47,13 @@ object Delegates {
 }
 ```
 the import
-```
+```scala
 import delegate Delegates.{for Ordering[_], ExecutionContext}
 ```
 would import the `intOrd`, `listOrd`, and `ec` delegates but leave out the `im` delegate, since it fits none of the specified bounds.
 
 By-type imports can be mixed with by-name imports. If both are present in an import clause, by-type imports come last. For instance, the import clause
-```
+```scala
 import delegate Instances.{im, for Ordering[_]}
 ```
 would import `im`, `intOrd`, and `listOrd` but leave out `ec`. By-type imports cannot be mixed with a wildcard import in the same import clause.

docs/docs/reference/contextual/motivation.md

@@ -47,11 +47,11 @@ Existing Scala programmers by and large have gotten used to the status quo and s
 
 The following pages introduce a redesign of contextual abstractions in Scala. They introduce four fundamental changes:
 
- 1. [Delegates](./instance-defs.html) are a new way to define basic terms that can be synthesized.  They replace implicit definitions. The core principle of the proposal is that, rather than mixing the `implicit` modifier with a large number of features, we have a single way to define terms that can be synthesized for types.
+ 1. [Delegates](./delegates.html) are a new way to define basic terms that can be synthesized.  They replace implicit definitions. The core principle of the proposal is that, rather than mixing the `implicit` modifier with a large number of features, we have a single way to define terms that can be synthesized for types.
 
- 2. [Given Clauses](./inferable-params.html) are a new syntax for implicit _parameters_ and their _arguments_. Both are introduced with the same keyword, `given`. This unambiguously aligns parameters and arguments, solving a number of language warts. It also allows us to have several implicit parameter sections, and to have implicit parameters followed by normal ones.
+ 2. [Given Clauses](./given-clauses.html) are a new syntax for implicit _parameters_ and their _arguments_. Both are introduced with the same keyword, `given`. This unambiguously aligns parameters and arguments, solving a number of language warts. It also allows us to have several implicit parameter sections, and to have implicit parameters followed by normal ones.
 
- 3. [Delegate Imports](./import-implied.html) are a new class of imports that specifically import delegates and nothing else. Delegates _must be_ imported with  `import delegate`, a plain import will no longer bring them into scope.
+ 3. [Delegate Imports](./import-delegate.html) are a new class of imports that specifically import delegates and nothing else. Delegates _must be_ imported with  `import delegate`, a plain import will no longer bring them into scope.
 
  4. [Implicit Conversions](./conversions.html) are now expressed as delegates of a standard `Conversion` class. All other forms of implicit conversions will be phased out.
 
@@ -63,8 +63,8 @@ This section also contains pages describing other language features that are rel
  - [Typeclass Derivation](./derivation.html) introduces constructs to automatically derive typeclass delegates for ADTs.
  - [Multiversal Equality](./multiversal-equality.html) introduces a special typeclass
   to support type safe equality.
- - [Implicit Function Types](./query-types.html) provide a way to abstract over given clauses.
- - [Implicit By-Name Parameters](./inferable-by-name-parameters.html) are an essential tool to define recursive synthesized values without looping.
+ - [Implicit Function Types](./implicit-function-types.html) provide a way to abstract over given clauses.
+ - [Implicit By-Name Parameters](./implicit-by-name-parameters.html) are an essential tool to define recursive synthesized values without looping.
  - [Relationship with Scala 2 Implicits](./relationship-implicits.html) discusses the relationship between old-style implicits and new-style delegates and given clauses and how to migrate from one to the other.
 
 Overall, the new design achieves a better separation of term inference from the rest of the language: There is a single way to define delegates instead of a multitude of forms all taking an `implicit` modifier. There is a single way to introduce implicit parameters and arguments instead of conflating implicit with normal arguments. There is a separate way to import delegates that does not allow them to hide in a sea of normal imports. And there is a single way to define an implicit conversion which is clearly marked as such and does not require special syntax.

docs/docs/reference/features-classification.md

@@ -20,7 +20,7 @@ These new constructs directly model core features of DOT, higher-kinded types, a
  - [Union types](https://dotty.epfl.ch/docs/reference/new-types/union-types.html),
  - [Type lambdas](https://dotty.epfl.ch/docs/reference/new-types/type-lambdas.html),
  replacing encodings using structural types and type projection.
- - [Context Queries](https://dotty.epfl.ch/docs/reference/contextual/query-types.html)
+ - [Context Queries](https://dotty.epfl.ch/docs/reference/contextual/implicit-function-types.html)
   (_aka_ implicit function types) offering abstraction over given parameters.
 
 **Status: essential**
@@ -36,9 +36,9 @@ Since these are additions, there's generally no migration cost for old code. An
 These constructs replace existing constructs with the aim of making the language safer and simpler to use, and to promote uniformity in code style.
 
  - [Trait Parameters](https://dotty.epfl.ch/docs/reference/other-new-features/trait-parameters.html) replace [early initializers](https://dotty.epfl.ch/docs/reference/dropped-features/early-initializers.html) with a more generally useful construct.
- - [Delegates](https://dotty.epfl.ch/docs/reference/contextual/instance-defs.html)
+ - [Delegates](https://dotty.epfl.ch/docs/reference/contextual/delegates.html)
    replace implicit objects and defs, focussing on intent over mechanism.
- - [Given Clauses](https://dotty.epfl.ch/docs/reference/contextual/inferable-params.html) replace implicit parameters, avoiding their ambiguities.
+ - [Given Clauses](https://dotty.epfl.ch/docs/reference/contextual/given-clauses.html) replace implicit parameters, avoiding their ambiguities.
  - [Extension Methods](https://dotty.epfl.ch/docs/reference/contextual/extension-methods.html) replace implicit classes with a clearer and simpler mechanism.
  - [Opaque Type Aliases](https://dotty.epfl.ch/docs/reference/other-new-features/opaques.html) replace most uses
    of value classes while guaranteeing absence of boxing.
@@ -71,7 +71,7 @@ For the next several versions, old features will remain available and deprecatio
 These constructs are restricted to make the language safer.
 
  - [Implicit Conversions](https://dotty.epfl.ch/docs/reference/contextual/conversions.html): there is only one way to define implicit conversions instead of many, and potentially surprising implicit conversions require a language import.
- - [Delegate Imports](https://dotty.epfl.ch/docs/reference/contextual/import-implied.html): implicits now require a special form of import, to make the import clearly visible.
+ - [Delegate Imports](https://dotty.epfl.ch/docs/reference/contextual/import-delegate.html): implicits now require a special form of import, to make the import clearly visible.
  - [Type Projection](https://dotty.epfl.ch/docs/reference/dropped-features/type-projection.html): only classes can be used as prefix `C` of a type projection `C#A`. Type projection on abstract types is no longer supported since it is unsound.
  - [Multiversal Equality](https://dotty.epfl.ch/docs/reference/contextual/multiversal-equality.html) implements an "opt-in" scheme to rule out nonsensical comparisons with `==` and `!=`.
  - [@infix and @alpha](https://github.com/lampepfl/dotty/pull/5975)
@@ -174,7 +174,7 @@ To enable porting most uses of macros, we are experimenting with the advanced la
 by itself a straightforward implementation of some simple macros and is at the same time an essential building block for the implementation of complex macros.
 - [Quotes and Splices](https://dotty.epfl.ch/docs/reference/metaprogramming/macros.html) provide a principled way to express macros and staging with a unified set of abstractions.
 - [Typeclass derivation](https://dotty.epfl.ch/docs/reference/contextual/derivation.html) provides an in-language implementation of the `Gen` macro in Shapeless and other foundational libraries. The new implementation is more robust, efficient and easier to use than the macro.
-- [Implicit by-name parameters](https://dotty.epfl.ch/docs/reference/contextual/inferable-by-name-parameters.html) provide a more robust in-language implementation of the `Lazy` macro in Shapeless.
+- [Implicit by-name parameters](https://dotty.epfl.ch/docs/reference/contextual/implicit-by-name-parameters.html) provide a more robust in-language implementation of the `Lazy` macro in Shapeless.
 - [Erased Terms](https://dotty.epfl.ch/docs/reference/metaprogramming/erased-terms.html) provide a general mechanism for compile-time-only computations.
 
 **Status: not yet settled**

docs/docs/reference/new-types/union-types.md

@@ -7,19 +7,15 @@ A union type `A | B` has as values all values of type `A` and also all values of
 
 
 ```scala
-case class UserName(name: String) {
-  def lookup(admin: Admin): UserData
-}
-case class Password(hash: Hash) {
-  def lookup(admin: Admin): UserData
-}
+case class UserName(name: String)
+case class Password(hash: Hash)
 
 def help(id: UserName | Password) = {
   val user = id match {
     case UserName(name) => lookupName(name)
     case Password(hash) => lookupPassword(hash)
   }
-  // ...
+  ...
 }
 ```
 

docs/docs/reference/overview.md

@@ -25,17 +25,17 @@ These new constructs directly model core features of DOT, higher-kinded types, a
  - [Union types](https://dotty.epfl.ch/docs/reference/new-types/union-types.html),
  - [Type lambdas](https://dotty.epfl.ch/docs/reference/new-types/type-lambdas.html),
  replacing encodings using structural types and type projection.
- - [Context Queries](https://dotty.epfl.ch/docs/reference/contextual/query-types.html)
+ - [Context Queries](https://dotty.epfl.ch/docs/reference/contextual/implicit-function-types.html)
   (_aka_ implicit function types) offering abstraction over implicit parameters.
 
 ## Simplifications
 
 These constructs replace existing constructs with the aim of making the language safer and simpler to use, and to promote uniformity in code style.
 
  - [Trait Parameters](https://dotty.epfl.ch/docs/reference/other-new-features/trait-parameters.html) replace [early initializers](https://dotty.epfl.ch/docs/reference/dropped-features/early-initializers.html) with a more generally useful construct.
- - [Delegates](https://dotty.epfl.ch/docs/reference/contextual/instance-defs.html)
+ - [Delegates](https://dotty.epfl.ch/docs/reference/contextual/delegates.html)
    replace implicit objects and defs, focussing on intent over mechanism.
- - [Given Clauses](https://dotty.epfl.ch/docs/reference/contextual/inferable-params.html) replace implicit parameters, avoiding their ambiguities.
+ - [Given Clauses](https://dotty.epfl.ch/docs/reference/contextual/given-clauses.html) replace implicit parameters, avoiding their ambiguities.
  - [Extension Methods](https://dotty.epfl.ch/docs/reference/contextual/extension-methods.html) replace implicit classes with a clearer and simpler mechanism.
  - [Opaque Type Aliases](https://dotty.epfl.ch/docs/reference/other-new-features/opaques.html) replace most uses
    of value classes while guaranteeing absence of boxing.
@@ -58,7 +58,7 @@ e a special case. There are currently no deprecation plans for value classes, si
 These constructs are restricted to make the language safer.
 
  - [Implicit Conversions](https://dotty.epfl.ch/docs/reference/contextual/conversions.html): there is only one way to define implicit conversions instead of many, and potentially surprising implicit conversions require a language import.
- - [Delegate Imports](https://dotty.epfl.ch/docs/reference/contextual/import-implied.html): implicits now require a special form of import, to make the import clearly visible.
+ - [Delegate Imports](https://dotty.epfl.ch/docs/reference/contextual/import-delegate.html): implicits now require a special form of import, to make the import clearly visible.
  - [Type Projection](https://dotty.epfl.ch/docs/reference/dropped-features/type-projection.html): only classes can be used as prefix `C` of a type projection `C#A`. Type projection on abstract types is no longer supported since it is unsound.
  - [Multiversal Equality](https://dotty.epfl.ch/docs/reference/contextual/multiversal-equality.html) implements an "opt-in" scheme to rule out nonsensical comparisons with `==` and `!=`.
  - [@infix and @alpha](https://github.com/lampepfl/dotty/pull/5975)
@@ -126,7 +126,7 @@ To enable porting most uses of macros, we are experimenting with the advanced la
 by itself a straightforward implementation of some simple macros and is at the same time an essential building block for the implementation of complex macros.
 - [Quotes and Splices](https://dotty.epfl.ch/docs/reference/metaprogramming/macros.html) provide a principled way to express macros and staging with a unified set of abstractions.
 - [Typeclass derivation](https://dotty.epfl.ch/docs/reference/contextual/derivation.html) provides an in-language implementation of the `Gen` macro in Shapeless and other foundational libraries. The new implementation is more robust, efficient and easier to use than the macro.
-- [Implicit by-name parameters](https://dotty.epfl.ch/docs/reference/contextual/inferable-by-name-parameters.html) provide a more robust in-language implementation of the `Lazy` macro in Shapeless.
+- [Implicit by-name parameters](https://dotty.epfl.ch/docs/reference/contextual/implicit-by-name-parameters.html) provide a more robust in-language implementation of the `Lazy` macro in Shapeless.
 - [Erased Terms](https://dotty.epfl.ch/docs/reference/metaprogramming/erased-terms.html) provide a general mechanism for compile-time-only computations.
 
 ## See Also