From 8d00ed1ec07ac64d0c3165c366915229164a615e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?St=C3=A9phane=20Micheloud?= <stephane.micheloud@gmail.com>
Date: Wed, 6 Jan 2021 23:55:58 +0100
Subject: [PATCH 1/2] more fixes in Markdown files

---
 .../changed-features/eta-expansion-spec.md    |  2 +-
 .../implicit-conversions-spec.md              |  8 +++---
 .../reference/changed-features/operators.md   |  2 +-
 .../changed-features/structural-types-spec.md |  6 +++--
 .../contextual/context-functions-spec.md      |  6 ++---
 .../reference/contextual/extension-methods.md |  2 +-
 .../contextual/multiversal-equality.md        | 23 +++++++++++++----
 .../right-associative-extension-methods.md    | 10 ++++++--
 .../dropped-features/weak-conformance-spec.md |  5 ++--
 .../docs/reference/features-classification.md | 18 ++++++-------
 .../dependent-function-types-spec.md          | 25 ++++++++++++++++++-
 .../reference/other-new-features/matchable.md | 14 ++++++-----
 .../other-new-features/targetName.md          |  2 +-
 .../threadUnsafe-annotation.md                |  8 +++---
 docs/docs/reference/syntax.md                 |  2 +-
 15 files changed, 90 insertions(+), 43 deletions(-)

diff --git a/docs/docs/reference/changed-features/eta-expansion-spec.md b/docs/docs/reference/changed-features/eta-expansion-spec.md
index 172c7c1be0be..3cbc40d1f9c5 100644
--- a/docs/docs/reference/changed-features/eta-expansion-spec.md
+++ b/docs/docs/reference/changed-features/eta-expansion-spec.md
@@ -18,7 +18,7 @@ def m(x: Int, y: String) = ???
 val f = m // becomes: val f = (x: Int, y: String) => m(x, y)
 ```
 
-In Scala 2, a method reference `m` was converted to a function value only if the expected type was a function type, which means the conversion in the example above would not have been triggered, because `val f` does not have a type ascription. To still get eta-expansion, a shortcut `m _` would force the conversion.
+In Scala 2, a method reference `m` is converted to a function value only if the expected type is a function type, which means the conversion in the example above would not have been triggered, because `val f` does not have a type ascription. To still get eta-expansion, a shortcut `m _` would force the conversion.
 
 For methods with one or more parameters like in the example above, this restriction has now been dropped. The syntax `m _` is no longer needed and will be deprecated in the future.
 
diff --git a/docs/docs/reference/changed-features/implicit-conversions-spec.md b/docs/docs/reference/changed-features/implicit-conversions-spec.md
index 5df0f5f0ac46..652e32f2da51 100644
--- a/docs/docs/reference/changed-features/implicit-conversions-spec.md
+++ b/docs/docs/reference/changed-features/implicit-conversions-spec.md
@@ -87,10 +87,10 @@ Scala 3.
 
 ## Motivation for the changes
 
-The introduction of `Conversion` in Scala 3 and the decision to
-restrict implicit values of this type to be considered as potential
-views comes from the desire to remove surprising behavior from the
-language:
+The introduction of [`scala.Conversion`](https://github.com/lampepfl/dotty/blob/master/library/src/scala/Conversion.scala)
+in Scala 3 and the decision to restrict implicit values of this type to be
+considered as potential views comes from the desire to remove surprising
+behavior from the language:
 
 ```scala
 implicit val m: Map[Int, String] = Map(1 -> "abc")
diff --git a/docs/docs/reference/changed-features/operators.md b/docs/docs/reference/changed-features/operators.md
index 0d1faa67cfae..7df48ac9898a 100644
--- a/docs/docs/reference/changed-features/operators.md
+++ b/docs/docs/reference/changed-features/operators.md
@@ -6,7 +6,7 @@ title: "Rules for Operators"
 The rules for infix operators have changed in some parts:
 
 First, an alphanumeric method can be used as an infix operator only if its definition carries an `infix` modifier. Second, it is recommended (but not enforced) to
-augment definitions of symbolic operators with `@targetName` annotations. Finally,
+augment definitions of symbolic operators with [`@targetName` annotations](../other-new-features/targetName.md). Finally,
 a syntax change allows infix operators to be written on the left in a multi-line expression.
 
 ## The `infix` Modifier
diff --git a/docs/docs/reference/changed-features/structural-types-spec.md b/docs/docs/reference/changed-features/structural-types-spec.md
index 4de11e2d5d50..b3e2125d7dcf 100644
--- a/docs/docs/reference/changed-features/structural-types-spec.md
+++ b/docs/docs/reference/changed-features/structural-types-spec.md
@@ -14,7 +14,8 @@ RefineStat    ::= ‘val’ VarDcl | ‘def’ DefDcl | ‘type’ {nl} TypeDcl
 
 ## Implementation of structural types
 
-The standard library defines a universal marker trait `Selectable` in the package `scala`:
+The standard library defines a universal marker trait
+[`scala.Selectable`](https://github.com/lampepfl/dotty/blob/master/library/src/scala/Selectable.scala):
 
 ```scala
 trait Selectable extends Any
@@ -78,7 +79,8 @@ and `Rs` are structural refinement declarations, and given `v.a` of type `U`, we
   type, an error is emitted.
 
 Note that `v`'s static type does not necessarily have to conform to `Selectable`, nor does it need to have `selectDynamic` and `applyDynamic` as members. It suffices that there is an implicit
-conversion that can turn `v` into a `Selectable`, and the selection methods could also be available as extension methods.
+conversion that can turn `v` into a `Selectable`, and the selection methods could also be available as
+[extension methods](../contextual/extension-methods.md).
 
 ## Limitations of structural types
 
diff --git a/docs/docs/reference/contextual/context-functions-spec.md b/docs/docs/reference/contextual/context-functions-spec.md
index d5e1eaa61ca7..e910bd5263f1 100644
--- a/docs/docs/reference/contextual/context-functions-spec.md
+++ b/docs/docs/reference/contextual/context-functions-spec.md
@@ -20,12 +20,12 @@ Context function types associate to the right, e.g.
 Context function types are shorthands for class types that define `apply`
 methods with context parameters. Specifically, the `N`-ary function type
 `T1, ..., TN => R` is a shorthand for the class type
-`ContextFunctionN[T1 , ... , TN, R]`. Such class types are assumed to have the following definitions, for any value of `N >= 1`:
+`ContextFunctionN[T1, ..., TN, R]`. Such class types are assumed to have the following definitions, for any value of `N >= 1`:
 
 ```scala
 package scala
-trait ContextFunctionN[-T1 , ... , -TN, +R]:
-   def apply(using x1: T1 , ... , xN: TN): R
+trait ContextFunctionN[-T1, ..., -TN, +R]:
+   def apply(using x1: T1, ..., xN: TN): R
 ```
 
 Context function types erase to normal function types, so these classes are
diff --git a/docs/docs/reference/contextual/extension-methods.md b/docs/docs/reference/contextual/extension-methods.md
index b650e2ea81cb..346e3293c62f 100644
--- a/docs/docs/reference/contextual/extension-methods.md
+++ b/docs/docs/reference/contextual/extension-methods.md
@@ -60,7 +60,7 @@ the right-associative operator `+:` to an extension method. This is analogous
 to the implementation of right binding operators as normal methods. The Scala
 compiler preprocesses an infix operation `x +: xs` to `xs.+:(x)`, so the extension
 method ends up being applied to the sequence as first argument (in other words, the
-two swaps cancel each other out). See [here for details](./right-associative-extension-methods.html).
+two swaps cancel each other out). See [here for details](./right-associative-extension-methods.md).
 
 ### Generic Extensions
 
diff --git a/docs/docs/reference/contextual/multiversal-equality.md b/docs/docs/reference/contextual/multiversal-equality.md
index fdd429943844..0a9af4abc3b5 100644
--- a/docs/docs/reference/contextual/multiversal-equality.md
+++ b/docs/docs/reference/contextual/multiversal-equality.md
@@ -23,18 +23,22 @@ If `y` gets compared to other values of type `T`,
 the program will still typecheck, since values of all types can be compared with each other.
 But it will probably give unexpected results and fail at runtime.
 
-Multiversal equality is an opt-in way to make universal equality
-safer. It uses a binary type class `CanEqual` to indicate that values of
-two given types can be compared with each other.
+Multiversal equality is an opt-in way to make universal equality safer.
+It uses a binary type class [`scala.CanEqual`](https://github.com/lampepfl/dotty/blob/master/library/src/scala/CanEqual.scala)
+to indicate that values of two given types can be compared with each other.
 The example above would not typecheck if `S` or `T` was a class
 that derives `CanEqual`, e.g.
+
 ```scala
 class T derives CanEqual
 ```
+
 Alternatively, one can also provide a `CanEqual` given instance directly, like this:
+
 ```scala
 given CanEqual[T, T] = CanEqual.derived
 ```
+
 This definition effectively says that values of type `T` can (only) be
 compared to other values of type `T` when using `==` or `!=`. The definition
 affects type checking but it has no significance for runtime
@@ -42,6 +46,7 @@ behavior, since `==` always maps to `equals` and `!=` always maps to
 the negation of `equals`. The right hand side `CanEqual.derived` of the definition
 is a value that has any `CanEqual` instance as its type. Here is the definition of class
 `CanEqual` and its companion object:
+
 ```scala
 package scala
 import annotation.implicitNotFound
@@ -63,7 +68,9 @@ given CanEqual[B, B] = CanEqual.derived
 given CanEqual[A, B] = CanEqual.derived
 given CanEqual[B, A] = CanEqual.derived
 ```
-The `scala.CanEqual` object defines a number of `CanEqual` given instances that together
+
+The [`scala.CanEqual`](https://github.com/lampepfl/dotty/blob/master/library/src/scala/CanEqual.scala)
+object defines a number of `CanEqual` given instances that together
 define a rule book for what standard types can be compared (more details below).
 
 There is also a "fallback" instance named `canEqualAny` that allows comparisons
@@ -73,7 +80,8 @@ over all types that do not themselves have a `CanEqual` given.  `canEqualAny` is
 def canEqualAny[L, R]: CanEqual[L, R] = CanEqual.derived
 ```
 
-Even though `canEqualAny` is not declared as `given`, the compiler will still construct an `canEqualAny` instance as answer to an implicit search for the
+Even though `canEqualAny` is not declared as `given`, the compiler will still
+construct an `canEqualAny` instance as answer to an implicit search for the
 type `CanEqual[L, R]`, unless `L` or `R` have `CanEqual` instances
 defined on them, or the language feature `strictEquality` is enabled.
 
@@ -90,16 +98,21 @@ or with a command line option `-language:strictEquality`.
 ## Deriving CanEqual Instances
 
 Instead of defining `CanEqual` instances directly, it is often more convenient to derive them. Example:
+
 ```scala
 class Box[T](x: T) derives CanEqual
 ```
+
 By the usual rules of [type class derivation](./derivation.md),
 this generates the following `CanEqual` instance in the companion object of `Box`:
+
 ```scala
 given [T, U](using CanEqual[T, U]): CanEqual[Box[T], Box[U]] =
    CanEqual.derived
 ```
+
 That is, two boxes are comparable with `==` or `!=` if their elements are. Examples:
+
 ```scala
 new Box(1) == new Box(1L)   // ok since there is an instance for `CanEqual[Int, Long]`
 new Box(1) == new Box("a")  // error: can't compare
diff --git a/docs/docs/reference/contextual/right-associative-extension-methods.md b/docs/docs/reference/contextual/right-associative-extension-methods.md
index 64b7da8e695c..798370c4c373 100644
--- a/docs/docs/reference/contextual/right-associative-extension-methods.md
+++ b/docs/docs/reference/contextual/right-associative-extension-methods.md
@@ -18,8 +18,10 @@ This is then followed by `def`, the method name, and possibly further parameters
             (using d: D)                      // <-- trailingUsing
     def +:: (y: Y)(using e: E)(z: Z)          // <-- otherParams
 ```
-An extension method is treated as a right associative operator if
-it has a name ending in `:` and is immediately followed by a
+
+An extension method is treated as a right-associative operator
+(as in [SLS §6.12.3](https://www.scala-lang.org/files/archive/spec/2.13/06-expressions.html#infix-operations))
+if it has a name ending in `:` and is immediately followed by a
 single parameter. In the example above, that parameter is `(y: Y)`.
 
 The Scala compiler pre-processes a right-associative infix operation such as `x +: xs`
@@ -28,10 +30,13 @@ is defined in the class of its right operand. To make up for this swap,
 the expansion of right-associative extension methods performs an analogous parameter swap. More precisely, if `otherParams` consists of a single parameter
 `rightParam` followed by `remaining`, the total parameter sequence
 of the extension method's expansion is:
+
 ```
     leadingUsing  rightParam  trailingUsing  extensionParam  remaining
 ```
+
 For instance, the `+::` method above would become
+
 ```scala
   <extension> def +:: (using a: A, b: B)(using c: C)
                       (y: Y)
@@ -39,6 +44,7 @@ For instance, the `+::` method above would become
                       (x: X)
                       (using e: E)(z: Z)
 ```
+
 This expansion has to be kept in mind when writing right-associative extension
 methods with inter-parameter dependencies.
 
diff --git a/docs/docs/reference/dropped-features/weak-conformance-spec.md b/docs/docs/reference/dropped-features/weak-conformance-spec.md
index e934d43af940..8e929f91c4f5 100644
--- a/docs/docs/reference/dropped-features/weak-conformance-spec.md
+++ b/docs/docs/reference/dropped-features/weak-conformance-spec.md
@@ -3,8 +3,9 @@ layout: doc-page
 title: "Dropped: Weak Conformance - More Details"
 ---
 
-To simplify the underlying type theory, Scala 3 drops the notion of weak
-conformance altogether. Instead, it provides more flexibility when
+To simplify the underlying type theory, Scala 3 drops the notion of
+[*weak conformance*](https://www.scala-lang.org/files/archive/spec/2.13/03-types.html#weak-conformance)
+altogether. Instead, it provides more flexibility when
 assigning a type to a constant expression. The new rule is:
 
  - If a list of expressions `Es` appears as one of
diff --git a/docs/docs/reference/features-classification.md b/docs/docs/reference/features-classification.md
index 1b729987a980..732eaa13a381 100644
--- a/docs/docs/reference/features-classification.md
+++ b/docs/docs/reference/features-classification.md
@@ -20,7 +20,7 @@ These new constructs directly model core features of [DOT](https://www.scala-lan
  - [Union types](new-types/union-types.md),
  - [Type lambdas](new-types/type-lambdas.md),
  replacing encodings using structural types and type projection.
- - [Context Functions](contextual/context-functions.md) offering abstraction over given parameters.
+ - [Context functions](contextual/context-functions.md) offering abstraction over given parameters.
 
 **Status: essential**
 
@@ -37,7 +37,7 @@ These constructs replace existing constructs with the aim of making the language
  - [Trait parameters](other-new-features/trait-parameters.md) replace [early initializers](dropped-features/early-initializers.md) with a more generally useful construct.
  - [Given instances](contextual/givens.md)
    replace implicit objects and defs, focussing on intent over mechanism.
- - [Using Clauses](contextual/using-clauses.md) replace implicit parameters, avoiding their ambiguities.
+ - [Using clauses](contextual/using-clauses.md) replace implicit parameters, avoiding their ambiguities.
  - [Extension methods](contextual/extension-methods.md) replace implicit classes with a clearer and simpler mechanism.
  - [Opaque type aliases](other-new-features/opaques.md) replace most uses
    of value classes while guaranteeing absence of boxing.
@@ -72,7 +72,7 @@ These constructs are restricted to make the language safer.
  - [Implicit Conversions](contextual/conversions.md): there is only one way to define implicit conversions instead of many, and potentially surprising implicit conversions require a language import.
  - [Given Imports](contextual/import-delegate.md): implicits now require a special form of import, to make the import clearly visible.
  - [Type Projection](dropped-features/type-projection.md): 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](contextual/multiversal-equality.md) implements an "opt-in" scheme to rule out nonsensical comparisons with `==` and `!=`.
+ - [Multiversal equality](contextual/multiversal-equality.md) implements an "opt-in" scheme to rule out nonsensical comparisons with `==` and `!=`.
  - [infix](https://github.com/lampepfl/dotty/pull/5975)
  makes method application syntax uniform across code bases.
 
@@ -147,10 +147,10 @@ Only a few programs should require changes, but some necessary changes might be
 These are additions to the language that make it more powerful or pleasant to use.
 
  - [Enums](enums/enums.md) provide concise syntax for enumerations and [algebraic data types](enums/adts.md).
- - [Parameter Untupling](other-new-features/parameter-untupling.md) avoids having to use `case` for tupled parameter destructuring.
- - [Dependent Function Types](new-types/dependent-function-types.md) generalize dependent methods to dependent function values and types.
- - [Polymorphic Function Types](https://github.com/lampepfl/dotty/pull/4672) generalize polymorphic methods to dependent function values and types. _Current status_: There is a proposal, and a prototype implementation, but the implementation has not been finalized or merged yet.
- - [Kind Polymorphism](other-new-features/kind-polymorphism.md) allows the definition of operators working equally on types and type constructors.
+ - [Parameter untupling](other-new-features/parameter-untupling.md) avoids having to use `case` for tupled parameter destructuring.
+ - [Dependent function types](new-types/dependent-function-types.md) generalize dependent methods to dependent function values and types.
+ - [Polymorphic function types](https://github.com/lampepfl/dotty/pull/4672) generalize polymorphic methods to dependent function values and types. _Current status_: There is a proposal, and a prototype implementation, but the implementation has not been finalized or merged yet.
+ - [Kind polymorphism](other-new-features/kind-polymorphism.md) allows the definition of operators working equally on types and type constructors.
 
 **Status: mixed**
 
@@ -168,10 +168,10 @@ It's worth noting that macros were never included in the Scala 2 language specif
 
 To enable porting most uses of macros, we are experimenting with the advanced language constructs listed below. These designs are more provisional than the rest of the proposed language constructs for Scala 3.0. There might still be some changes until the final release. Stabilizing the feature set needed for metaprogramming is our first priority.
 
-- [Match Types](new-types/match-types.md) allow computation on types.
+- [Match types](new-types/match-types.md) allow computation on types.
 - [Inline](metaprogramming/inline.md) provides
 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](metaprogramming/macros.md) provide a principled way to express macros and staging with a unified set of abstractions.
+- [Quotes and splices](metaprogramming/macros.md) provide a principled way to express macros and staging with a unified set of abstractions.
 - [Type class derivation](contextual/derivation.md) 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](contextual/implicit-by-name-parameters.md) provide a more robust in-language implementation of the `Lazy` macro in Shapeless.
 
diff --git a/docs/docs/reference/new-types/dependent-function-types-spec.md b/docs/docs/reference/new-types/dependent-function-types-spec.md
index 944fec44ff86..1105258395a0 100644
--- a/docs/docs/reference/new-types/dependent-function-types-spec.md
+++ b/docs/docs/reference/new-types/dependent-function-types-spec.md
@@ -42,7 +42,30 @@ same way that other functions do, see
 
 ## Examples
 
-- [depfuntype.scala](https://github.com/lampepfl/dotty/blob/master/tests/pos/depfuntype.scala)
+The example below defines a trait `C` and the two dependent function types
+`DF` and `IDF` and prints the results of the respective function applications:
+
+[depfuntype.scala]: https://github.com/lampepfl/dotty/blob/master/tests/pos/depfuntype.scala
+
+```scala
+trait C { type M; val m: M }
+
+type DF = (x: C) => x.M
+
+type IDF = (x: C) ?=> x.M
+
+@main def test =
+   val c = new C { type M = Int; val m = 3 }
+
+   val depfun: DF = (x: C) => x.m
+   val t = depfun(c)
+   println(s"t=$t")   // prints "t=3"
+
+   val idepfun: IDF = summon[C].m
+   val u = idepfun(using c)
+   println(s"u=$u")   // prints "u=3"
+
+```
 
 - [eff-dependent.scala](https://github.com/lampepfl/dotty/blob/master/tests/run/eff-dependent.scala)
 
diff --git a/docs/docs/reference/other-new-features/matchable.md b/docs/docs/reference/other-new-features/matchable.md
index cdf31e3793c7..c4814af64f3f 100644
--- a/docs/docs/reference/other-new-features/matchable.md
+++ b/docs/docs/reference/other-new-features/matchable.md
@@ -109,12 +109,14 @@ class C(val x: String):
          case that: C => this.x == that.x
          case _ => false
 ```
+
 The cast of `that` to `Matchable` serves as an indication that universal equality
 is unsafe in the presence of abstract types and opaque types since it cannot properly distinguish the meaning of a type from its representation. The cast
 is guaranteed to succeed at run-time since `Any` and `Matchable` both erase to
 `Object`.
 
 For instance, consider the definitions
+
 ```scala
 opaque type Meter = Double
 def Meter(x: Double) = x
@@ -122,17 +124,17 @@ def Meter(x: Double) = x
 opaque type Second = Double
 def Second(x: Double) = x
 ```
+
 Here, universal `equals` will return true for
+
 ```scala
    Meter(10).equals(Second(10))
 ```
-even though this is clearly false mathematically. With [multiversal equality](../contextual/multiversal-equality.html) one can mitigate that problem somewhat by turning
+
+even though this is clearly false mathematically. With [multiversal equality](../contextual/multiversal-equality.md) one can mitigate that problem somewhat by turning
+
 ```scala
    Meter(10) == Second(10)
 ```
-into a type error.
-
-
-
-
 
+into a type error.
diff --git a/docs/docs/reference/other-new-features/targetName.md b/docs/docs/reference/other-new-features/targetName.md
index 865ebaa0ef69..572d7a5e2146 100644
--- a/docs/docs/reference/other-new-features/targetName.md
+++ b/docs/docs/reference/other-new-features/targetName.md
@@ -1,6 +1,6 @@
 ---
 layout: doc-page
-title: The @targetName annotation
+title: "The @targetName annotation"
 ---
 
 A `@targetName` annotation on a definition defines an alternate name for the implementation of that definition. Example:
diff --git a/docs/docs/reference/other-new-features/threadUnsafe-annotation.md b/docs/docs/reference/other-new-features/threadUnsafe-annotation.md
index 6bcd426425b1..2c5a3df9c82c 100644
--- a/docs/docs/reference/other-new-features/threadUnsafe-annotation.md
+++ b/docs/docs/reference/other-new-features/threadUnsafe-annotation.md
@@ -1,11 +1,11 @@
 ---
 layout: doc-page
-title: threadUnsafe annotation
+title: "The @threadUnsafe annotation"
 ---
 
-A new annotation `@threadUnsafe` can be used on a field which defines a `lazy
-val`. When this annotation is used, the initialization of the lazy val will use a
-faster mechanism which is not thread-safe.
+A new annotation `@threadUnsafe` can be used on a field which defines
+a `lazy val`. When this annotation is used, the initialization of the
+`lazy val` will use a faster mechanism which is not thread-safe.
 
 ### Example
 
diff --git a/docs/docs/reference/syntax.md b/docs/docs/reference/syntax.md
index b37ecf514a1c..71d3ef19cbd8 100644
--- a/docs/docs/reference/syntax.md
+++ b/docs/docs/reference/syntax.md
@@ -3,7 +3,7 @@ layout: doc-page
 title: "Scala 3 Syntax Summary"
 ---
 
-The following descriptions of Scala tokens uses literal characters `‘c’` when
+The following description of Scala tokens uses literal characters `‘c’` when
 referring to the ASCII fragment `\u0000` – `\u007F`.
 
 _Unicode escapes_ are used to represent the [Unicode character](https://www.w3.org/International/articles/definitions-characters/) with the given

From f72855e8b61d26ab16fca3d323bcc6e6a971dbf9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?St=C3=A9phane=20Micheloud?= <stephane.micheloud@gmail.com>
Date: Thu, 7 Jan 2021 12:08:25 +0100
Subject: [PATCH 2/2] addressed review comment

---
 .../contextual/implicit-by-name-parameters.md |  7 ---
 .../reference/contextual/import-delegate.md   |  7 ---
 .../reference/contextual/import-implied.md    |  6 ---
 .../inferable-by-name-parameters.md           |  6 ---
 .../reference/contextual/inferable-params.md  |  6 ---
 .../reference/contextual/instance-defs.md     |  6 ---
 .../reference/contextual/query-types-spec.md  |  6 ---
 docs/docs/reference/contextual/query-types.md |  6 ---
 .../dependent-function-types-spec.md          | 52 ++++++++++++++++++-
 .../implicit-by-name-parameters.md            |  5 --
 10 files changed, 51 insertions(+), 56 deletions(-)
 delete mode 100644 docs/docs/reference/contextual/implicit-by-name-parameters.md
 delete mode 100644 docs/docs/reference/contextual/import-delegate.md
 delete mode 100644 docs/docs/reference/contextual/import-implied.md
 delete mode 100644 docs/docs/reference/contextual/inferable-by-name-parameters.md
 delete mode 100644 docs/docs/reference/contextual/inferable-params.md
 delete mode 100644 docs/docs/reference/contextual/instance-defs.md
 delete mode 100644 docs/docs/reference/contextual/query-types-spec.md
 delete mode 100644 docs/docs/reference/contextual/query-types.md
 delete mode 100644 docs/docs/reference/other-new-features/implicit-by-name-parameters.md

diff --git a/docs/docs/reference/contextual/implicit-by-name-parameters.md b/docs/docs/reference/contextual/implicit-by-name-parameters.md
deleted file mode 100644
index 52aa41b50daf..000000000000
--- a/docs/docs/reference/contextual/implicit-by-name-parameters.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-layout: doc-page
-title: "Implicit By-Name Parameters"
----
-
-The contents of this page have [moved](./by-name-context-parameters.md).
-
diff --git a/docs/docs/reference/contextual/import-delegate.md b/docs/docs/reference/contextual/import-delegate.md
deleted file mode 100644
index 09af1f3cc30c..000000000000
--- a/docs/docs/reference/contextual/import-delegate.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-layout: doc-page
-title: "Import Given"
----
-
-The contents of this page have [moved](./given-imports.md).
-
diff --git a/docs/docs/reference/contextual/import-implied.md b/docs/docs/reference/contextual/import-implied.md
deleted file mode 100644
index f5c31327e07a..000000000000
--- a/docs/docs/reference/contextual/import-implied.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-layout: doc-page
-title: "Import Implied"
----
-
-The contents of this page have [moved](./given-imports.md).
diff --git a/docs/docs/reference/contextual/inferable-by-name-parameters.md b/docs/docs/reference/contextual/inferable-by-name-parameters.md
deleted file mode 100644
index b5f0d5d12351..000000000000
--- a/docs/docs/reference/contextual/inferable-by-name-parameters.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-layout: doc-page
-title: "Inferable-By-Name Parameters"
----
-
-The contents of this page have [moved](./by-name-context-parameters.md).
diff --git a/docs/docs/reference/contextual/inferable-params.md b/docs/docs/reference/contextual/inferable-params.md
deleted file mode 100644
index b942e3f5e6b1..000000000000
--- a/docs/docs/reference/contextual/inferable-params.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-layout: doc-page
-title: "Inferable Params"
----
-
-The contents of this page have [moved](./using-clauses.md).
diff --git a/docs/docs/reference/contextual/instance-defs.md b/docs/docs/reference/contextual/instance-defs.md
deleted file mode 100644
index 32ae9c983ae1..000000000000
--- a/docs/docs/reference/contextual/instance-defs.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-layout: doc-page
-title: "Givens"
----
-
-The contents of this page have [moved](./givens.md).
diff --git a/docs/docs/reference/contextual/query-types-spec.md b/docs/docs/reference/contextual/query-types-spec.md
deleted file mode 100644
index ea9656e14fd6..000000000000
--- a/docs/docs/reference/contextual/query-types-spec.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-layout: doc-page
-title: "Query Types Spec"
----
-
-The contents of this page have [moved](./context-functions-spec.md).
diff --git a/docs/docs/reference/contextual/query-types.md b/docs/docs/reference/contextual/query-types.md
deleted file mode 100644
index 5e9eda63710e..000000000000
--- a/docs/docs/reference/contextual/query-types.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-layout: doc-page
-title: "Query Types"
----
-
-The contents of this page have [moved](./context-functions.md).
diff --git a/docs/docs/reference/new-types/dependent-function-types-spec.md b/docs/docs/reference/new-types/dependent-function-types-spec.md
index 1105258395a0..5f9bf9cf5f6a 100644
--- a/docs/docs/reference/new-types/dependent-function-types-spec.md
+++ b/docs/docs/reference/new-types/dependent-function-types-spec.md
@@ -67,7 +67,57 @@ type IDF = (x: C) ?=> x.M
 
 ```
 
-- [eff-dependent.scala](https://github.com/lampepfl/dotty/blob/master/tests/run/eff-dependent.scala)
+In the following example the depend type `f.Eff` refers to the effect type `CanThrow`:
+
+[eff-dependent.scala]: https://github.com/lampepfl/dotty/blob/master/tests/run/eff-dependent.scala
+
+```scala
+trait Effect
+
+// Type X => Y
+abstract class Fun[-X, +Y]:
+   type Eff <: Effect
+   def apply(x: X): Eff ?=> Y
+
+class CanThrow extends Effect
+class CanIO extends Effect
+
+given ct: CanThrow = new CanThrow
+given ci: CanIO = new CanIO
+
+class I2S extends Fun[Int, String]:
+   type Eff = CanThrow
+   def apply(x: Int) = x.toString
+
+class S2I extends Fun[String, Int]:
+   type Eff = CanIO
+   def apply(x: String) = x.length
+
+// def map(f: A => B)(xs: List[A]): List[B]
+def map[A, B](f: Fun[A, B])(xs: List[A]): f.Eff ?=> List[B] =
+   xs.map(f.apply)
+
+// def mapFn[A, B]: (A => B) -> List[A] -> List[B]
+def mapFn[A, B]: (f: Fun[A, B]) => List[A] => f.Eff ?=> List[B] =
+   f => xs => map(f)(xs)
+
+// def compose(f: A => B)(g: B => C)(x: A): C
+def compose[A, B, C](f: Fun[A, B])(g: Fun[B, C])(x: A):
+   f.Eff ?=> g.Eff ?=> C =
+   g(f(x))
+
+// def composeFn: (A => B) -> (B => C) -> A -> C
+def composeFn[A, B, C]:
+   (f: Fun[A, B]) => (g: Fun[B, C]) => A => f.Eff ?=> g.Eff ?=> C =
+   f => g => x => compose(f)(g)(x)
+
+@main def test =
+   val i2s = new I2S
+   val s2i = new S2I
+
+   assert(mapFn(i2s)(List(1, 2, 3)).mkString == "123")
+   assert(composeFn(i2s)(s2i)(22) == 2)
+```
 
 ### Type Checking
 
diff --git a/docs/docs/reference/other-new-features/implicit-by-name-parameters.md b/docs/docs/reference/other-new-features/implicit-by-name-parameters.md
deleted file mode 100644
index 80c42ca4c46b..000000000000
--- a/docs/docs/reference/other-new-features/implicit-by-name-parameters.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-layout: doc-page
-title: "Implicit By-Name Parameters"
----
-The contents of this page have [moved](../contextual/by-name-context-parameters.md).