Merge pull request #6684 from dotty-staging/doc-fixes

Docs polishings

Author: biboudis

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 renamed to 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 renamed to 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/inferable-by-name-parameters.md renamed to docs/docs/reference/contextual/implicit-by-name-parameters.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/query-types-spec.md renamed to docs/docs/reference/contextual/implicit-function-types-spec.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/query-types.md renamed to docs/docs/reference/contextual/implicit-function-types.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.