Merge pull request #11016 from michelou/scala3-docs

[docs/reference] more fixes in Markdown files

Author: liufengyun

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.
 

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")

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

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
 

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

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
 

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

@@ -23,25 +23,30 @@ 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
 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

docs/docs/reference/contextual/import-delegate.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,17 +30,21 @@ 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)
                       (using d: D)
                       (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.
 

docs/docs/reference/contextual/import-implied.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

docs/docs/reference/contextual/inferable-by-name-parameters.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.
 

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

@@ -42,9 +42,82 @@ 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:
 
-- [eff-dependent.scala](https://github.com/lampepfl/dotty/blob/master/tests/run/eff-dependent.scala)
+[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"
+
+```
+
+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