Add small improvements to the Reference page

Author: Sporarum

docs/_docs/reference/changed-features/compiler-plugins.md

@@ -4,18 +4,18 @@ title: "Changes in Compiler Plugins"
 nightlyOf: https://docs.scala-lang.org/scala3/reference/changed-features/compiler-plugins.html
 ---
 
-Compiler plugins are supported by Dotty (and Scala 3) since 0.9. There are two notable changes
-compared to `scalac`:
+Compiler plugins are supported in Scala 3 since Dotty 0.9. There are two notable changes
+compared to Scala 2:
 
 - No support for analyzer plugins
 - Added support for research plugins
 
-[Analyzer plugins][1] in `scalac` run during type checking and may influence
+[Analyzer plugins][1] run in Scala 2 during type checking and may influence
 normal type checking. This is a very powerful feature but for production usages,
 a predictable and consistent type checker is more important.
 
 For experimentation and research, Scala 3 introduces _research plugin_. Research plugins
-are more powerful than `scalac` analyzer plugins as they let plugin authors customize
+are more powerful than Scala 2 analyzer plugins as they let plugin authors customize
 the whole compiler pipeline. One can easily replace the standard typer by a custom one or
 create a parser for a domain-specific language. However, research plugins are only
 enabled for nightly or snaphot releases of Scala 3.
@@ -26,7 +26,7 @@ _standard plugins_ in Scala 3. In terms of features, they are similar to
 
 ## Using Compiler Plugins
 
-Both standard and research plugins can be used with `scalac` by adding the `-Xplugin:` option:
+In Scala 3, both standard and research plugins can be used with `scalac` by adding the `-Xplugin:` option:
 
 ```shell
 scalac -Xplugin:pluginA.jar -Xplugin:pluginB.jar Test.scala
@@ -40,7 +40,7 @@ the fully qualified plugin class name. The format of a property file is as follo
 pluginClass=dividezero.DivideZero
 ```
 
-This is different from `scalac` plugins that required a `scalac-plugin.xml` file.
+This is different from Scala 2 plugins that require a `scalac-plugin.xml` file.
 
 Starting from 1.1.5, `sbt` also supports Scala 3 compiler plugins. Please refer to the
 [`sbt` documentation][2] for more information.

docs/_docs/reference/changed-features/eta-expansion-spec.md

@@ -51,7 +51,7 @@ implicit val bla: Double = 1.0
 val bar = foo // val bar: Int => Float = ...
 ```
 
-## Automatic Eta-Expansion and query types
+## Automatic Eta-Expansion and context types
 
 A method with context parameters can be expanded to a value of a context type by writing the expected context type explicitly.
 
@@ -66,7 +66,7 @@ val bar: Double ?=> Float = foo(3)
 - If `m` is has an empty argument list (i.e. has type `()R`):
     1. If the expected type is of the form `() => T`, we eta expand.
     2. If m is defined by Java, or overrides a Java defined method, we insert `()`.
-    3. Otherwise we issue an error of the form:
+    3. Otherwise we issue an error of the form: `method must be called with () argument`
 
 Thus, an unapplied method with an empty argument list is only converted to a function when a function type is expected. It is considered best practice to either explicitly apply the method to `()`, or convert it to a function with `() => m()`.
 

docs/_docs/reference/changed-features/main-functions.md

@@ -72,7 +72,7 @@ final class happyBirthday:
       case error: CLP.ParseError => CLP.showError(error)
 ```
 
-**Note**: The `<static>` modifier above expresses that the `main` method is generated
+**Note:** The `<static>` modifier above expresses that the `main` method is generated
 as a static method of class `happyBirthDay`. It is not available for user programs in Scala. Regular "static" members are generated in Scala using objects instead.
 
 [`@main`](https://scala-lang.org/api/3.x/scala/main.html) methods are the recommended scheme to generate programs that can be invoked from the command line in Scala 3. They replace the previous scheme to write program as objects with a special `App` parent class. In Scala 2, `happyBirthday` could be written also like this:

docs/_docs/reference/contextual/by-name-context-parameters.md

@@ -53,7 +53,7 @@ In the example above, the definition of `s` would be expanded as follows.
 
 ```scala
 val s = summon[Test.Codec[Option[Int]]](
-  optionCodec[Int](using intCodec)
+  using optionCodec[Int](using intCodec)
 )
 ```
 

docs/_docs/reference/contextual/givens.md

@@ -10,8 +10,9 @@ that serve for synthesizing arguments to [context parameters](./using-clauses.md
 ```scala
 trait Ord[T]:
   def compare(x: T, y: T): Int
-  extension (x: T) def < (y: T) = compare(x, y) < 0
-  extension (x: T) def > (y: T) = compare(x, y) > 0
+  extension (x: T) 
+    def < (y: T) = compare(x, y) < 0
+    def > (y: T) = compare(x, y) > 0
 
 given intOrd: Ord[Int] with
   def compare(x: Int, y: Int) =
@@ -51,7 +52,7 @@ given [T](using Ord[T]): Ord[List[T]] with
 If the name of a given is missing, the compiler will synthesize a name from
 the implemented type(s).
 
-**Note** The name synthesized by the compiler is chosen to be readable and reasonably concise. For instance, the two instances above would get the names:
+**Note:** The name synthesized by the compiler is chosen to be readable and reasonably concise. For instance, the two instances above would get the names:
 
 ```scala
 given_Ord_Int
@@ -62,7 +63,7 @@ The precise rules for synthesizing names are found [here](./relationship-implici
 given instances of types that are "too similar". To avoid conflicts one can
 use named instances.
 
-**Note** To ensure robust binary compatibility, publicly available libraries should prefer named instances.
+**Note:** To ensure robust binary compatibility, publicly available libraries should prefer named instances.
 
 ## Alias Givens
 

docs/_docs/reference/contextual/multiversal-equality.md

@@ -33,6 +33,7 @@ that derives `CanEqual`, e.g.
 ```scala
 class T derives CanEqual
 ```
+> Normally a [derives clause](./derivation.md) accepts only type classes with one parameter, however there is a special case for `CanEqual`.
 
 Alternatively, one can also provide a `CanEqual` given instance directly, like this:
 
@@ -82,7 +83,7 @@ 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
+construct a `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.
 
@@ -156,10 +157,10 @@ Instances are defined so that every one of these types has a _reflexive_ `CanEqu
  - Primitive numeric types can be compared with subtypes of `java.lang.Number` (and _vice versa_).
  - `Boolean` can be compared with `java.lang.Boolean` (and _vice versa_).
  - `Char` can be compared with `java.lang.Character` (and _vice versa_).
- - Two sequences (of arbitrary subtypes of `scala.collection.Seq`) can be compared
+ - Two sequences (arbitrary subtypes of `scala.collection.Seq`) can be compared
    with each other if their element types can be compared. The two sequence types
    need not be the same.
- - Two sets (of arbitrary subtypes of `scala.collection.Set`) can be compared
+ - Two sets (arbitrary subtypes of `scala.collection.Set`) can be compared
    with each other if their element types can be compared. The two set types
    need not be the same.
  - Any subtype of `AnyRef` can be compared with `Null` (and _vice versa_).

docs/_docs/reference/contextual/type-classes.md

@@ -82,7 +82,7 @@ given Functor[List] with
     x.map(f) // List already has a `map` method
 ```
 
-With this `given` instance in scope, everywhere a `Functor` is expected, the compiler will accept a `List` to be used.
+With this `given` instance in scope, everywhere a type with a `Functor` context bound is expected, the compiler will accept a `List` to be used.
 
 For instance, we may write such a testing method:
 
@@ -214,7 +214,7 @@ instead of
 show(compute(i)(config))(config)
 ```
 
-Let's define this m then. First, we are going to define a type named `ConfigDependent` representing a function that when passed a `Config` produces a `Result`.
+Let's define this `flatMap` then. First, we are going to define a type named `ConfigDependent` representing a function that when passed a `Config` produces a `Result`.
 
 ```scala
 type ConfigDependent[Result] = Config => Result

docs/_docs/reference/dropped-features/delayed-init.md

@@ -18,7 +18,7 @@ object HelloWorld extends App {
 ```
 
 However, the code is now run in the initializer of the object, which on
-some JVM's means that it will only be interpreted. So, better not use it
+some JVMs means that it will only be interpreted. So, better not use it
 for benchmarking! Also, if you want to access the command line arguments,
 you need to use an explicit `main` method for that.
 

docs/_docs/reference/experimental/canthrow.md

@@ -124,7 +124,7 @@ try
   body
 catch ...
 ```
-Note that the right-hand side of the synthesized given is `???` (undefined). This is OK since
+Note that the right-hand side of the synthesized given is `compiletime.erasedValue`. This is OK since
 this given is erased; it will not be executed at runtime.
 
 **Note 1:** The [`saferExceptions`](https://scala-lang.org/api/3.x/scala/runtime/stdLibPatches/language$$experimental$$saferExceptions$.html) feature is designed to work only with checked exceptions. An exception type is _checked_ if it is a subtype of

docs/_docs/reference/experimental/cc.md

@@ -176,7 +176,7 @@ def f(x: {c}-> Int): Int
 ```
 Here, the actual argument to `f` is allowed to use the `c` capability but no others.
 
-**Note**: It is strongly recommended to write the capability set and the arrow `->` without intervening spaces,
+**Note:** It is strongly recommended to write the capability set and the arrow `->` without intervening spaces,
 as otherwise the notation would look confusingly like a function type.
 
 ## Subtyping and Subcapturing

docs/_docs/reference/experimental/explicit-nulls.md

@@ -540,4 +540,4 @@ Our strategy for binary compatibility with Scala binaries that predate explicit
 and new libraries compiled without `-Yexplicit-nulls` is to leave the types unchanged
 and be compatible but unsound.
 
-[More details](https://dotty.epfl.ch/docs/internals/explicit-nulls.html)
+[Implementation details](https://dotty.epfl.ch/docs/internals/explicit-nulls.html)

docs/_docs/reference/experimental/numeric-literals.md

@@ -4,7 +4,7 @@ title: "Numeric Literals"
 nightlyOf: https://docs.scala-lang.org/scala3/reference/experimental/numeric-literals.html
 ---
 
-**Note**: This feature is not yet part of the Scala 3 language definition. It can be made available by a language import:
+This feature is not yet part of the Scala 3 language definition. It can be made available by a language import:
 
 ```scala
 import scala.language.experimental.genericNumberLiterals

docs/_docs/reference/language-versions/source-compatibility.md

@@ -40,4 +40,4 @@ class C { ... }
 
 Language imports supersede command-line settings in the source files where they are specified. Only one language import specifying a source version is allowed in a source file, and it must come before any definitions in that file.
 
-**Note**: The [Scala 3 Migration Guide](https://docs.scala-lang.org/scala3/guides/migration/compatibility-intro.html) gives further information to help the Scala programmer moving from Scala 2.13 to Scala 3.
+**Note:** The [Scala 3 Migration Guide](https://docs.scala-lang.org/scala3/guides/migration/compatibility-intro.html) gives further information to help the Scala programmer moving from Scala 2.13 to Scala 3.

docs/_docs/reference/metaprogramming/compiletime-ops.md

@@ -11,7 +11,7 @@ The [`scala.compiletime`](https://scala-lang.org/api/3.x/scala/compiletime.html)
 ### `constValue` and `constValueOpt`
 
 `constValue` is a function that produces the constant value represented by a
-type.
+type, or a compile time error if the type is not a constant type.
 
 ```scala
 import scala.compiletime.constValue
@@ -30,6 +30,8 @@ enabling us to handle situations where a value is not present. Note that `S` is
 the type of the successor of some singleton type. For example the type `S[1]` is
 the singleton type `2`.
 
+Since tuples are not constant types, even if their constituants are, there is `constValueTuple`, which given a tuple type `(X1, ..., Xn)`, returns a tuple value `(constValue[X1], ..., constValue[Xn])`.
+
 ### `erasedValue`
 
 So far we have seen inline methods that take terms (tuples and integers) as
@@ -170,24 +172,24 @@ val concat: "a" + "b" = "ab"
 val addition: 1 + 1 = 2
 ```
 
-## Summoning Implicits Selectively
+## Summoning Givens Selectively
 
 It is foreseen that many areas of typelevel programming can be done with rewrite
 methods instead of implicits. But sometimes implicits are unavoidable. The
 problem so far was that the Prolog-like programming style of implicit search
 becomes viral: Once some construct depends on implicit search it has to be
 written as a logic program itself. Consider for instance the problem of creating
 a `TreeSet[T]` or a `HashSet[T]` depending on whether `T` has an `Ordering` or
-not. We can create a set of implicit definitions like this:
+not. We can create a set of given instances like this:
 
 ```scala
 trait SetFor[T, S <: Set[T]]
 
 class LowPriority:
-  implicit def hashSetFor[T]: SetFor[T, HashSet[T]] = ...
+  given hashSetFor[T]: SetFor[T, HashSet[T]] = ...
 
 object SetsFor extends LowPriority:
-  implicit def treeSetFor[T: Ordering]: SetFor[T, TreeSet[T]] = ...
+  given treeSetFor[T: Ordering]: SetFor[T, TreeSet[T]] = ...
 ```
 
 Clearly, this is not pretty. Besides all the usual indirection of implicit
@@ -236,18 +238,18 @@ inline def setFor[T]: Set[T] = summonFrom {
 
 `summonFrom` applications must be reduced at compile time.
 
-Consequently, if we summon an `Ordering[String]` the code above will return a
-new instance of `TreeSet[String]`.
+Consequently, if a given instance of `Ordering[String]` is in the implicit scope, the code above will return a
+new instance of `TreeSet[String]`. Such an instance is defined in `Ordering`'s companion object, so there will always be one.
 
 ```scala
-summon[Ordering[String]]
+summon[Ordering[String]] // Proves that an Ordering[String] is in scope
 
 println(setFor[String].getClass) // prints class scala.collection.immutable.TreeSet
 ```
 
-**Note** `summonFrom` applications can raise ambiguity errors. Consider the following
+**Note:** `summonFrom` applications can raise ambiguity errors. Consider the following
 code with two givens in scope of type `A`. The pattern match in `f` will raise
-an ambiguity error of `f` is applied.
+an ambiguity error if `f` is applied.
 
 ```scala
 class A

docs/_docs/reference/metaprogramming/metaprogramming.md

@@ -39,7 +39,7 @@ introduce the following fundamental facilities:
    representation of code. They can be parameterized and composed using
    splices, but their structure cannot be analyzed from the outside. TASTy
    reflection gives a way to analyze code structure by partly revealing the representation type of a piece of code in a standard API. The representation
-   type is a form of typed abstract syntax tree, which gives rise to the `TASTy`
+   type is a form of **t**yped **a**bstract **s**yntax **t**ree, which gives rise to the `TASTy`
    moniker.
 
 6. [TASTy Inspection](./tasty-inspect.md) Typed abstract syntax trees are serialized

docs/_docs/reference/new-types/type-lambdas-spec.md

@@ -103,9 +103,9 @@ type O2[X] = List[X]
 ```
 would be treated as covariant, `X` is used covariantly on its right-hand side.
 
-**Note**: The decision to treat `Nothing` as universal bottom type is provisional, and might be changed after further discussion.
+**Note:** The decision to treat `Nothing` as universal bottom type is provisional, and might be changed after further discussion.
 
-**Note**: Scala 2 and 3 differ in that Scala 2 also treats `Any` as universal top-type. This is not done in Scala 3. See also the discussion on [kind polymorphism](../other-new-features/kind-polymorphism.md)
+**Note:** Scala 2 and 3 differ in that Scala 2 also treats `Any` as universal top-type. This is not done in Scala 3. See also the discussion on [kind polymorphism](../other-new-features/kind-polymorphism.md)
 
 ## Curried Type Parameters
 

docs/_docs/reference/other-new-features/export.md

@@ -201,16 +201,16 @@ Consider the following example:
 
 ```scala
 class B { val c: Int }
-object a { val b = new B }
-export a.*
+object A { val b = new B }
+export A.*
 export b.*
 ```
 
-Is the `export b.*` clause legal? If yes, what does it export? Is it equivalent to `export a.b.*`? What about if we swap the last two clauses?
+Is the `export b.*` clause legal? If yes, what does it export? Is it equivalent to `export A.b.*`? What about if we swap the last two clauses?
 
 ```
 export b.*
-export a.*
+export A.*
 ```
 
 To avoid tricky questions like these, we fix the elaboration order of exports as follows.

docs/_docs/reference/other-new-features/kind-polymorphism.md

@@ -43,5 +43,5 @@ It is declared `abstract` and `final`, so it can be neither instantiated nor ext
 
 `AnyKind` plays a special role in Scala's subtype system: It is a supertype of all other types no matter what their kind is. It is also assumed to be kind-compatible with all other types. Furthermore, `AnyKind` is treated as a higher-kinded type (so it cannot be used as a type of values), but at the same time it has no type parameters (so it cannot be instantiated).
 
-**Note**: This feature is considered experimental but stable and it can be disabled under compiler flag
+**Note:** This feature is considered experimental but stable and it can be disabled under compiler flag
 (i.e. `-Yno-kind-polymorphism`).

docs/_docs/reference/other-new-features/opaques-details.md

@@ -65,7 +65,7 @@ opaque type G = [T] =>> List[T]
 but the following are not:
 ```scala
 opaque type BadF[T] = [U] =>> (T, U)
-opaque type BadG = [T] =>> [U] => (T, U)
+opaque type BadG = [T] =>> [U] =>> (T, U)
 ```
 
 ## Translation of Equality

docs/_docs/reference/other-new-features/parameter-untupling-spec.md

@@ -4,37 +4,7 @@ title: "Parameter Untupling - More Details"
 nightlyOf: https://docs.scala-lang.org/scala3/reference/other-new-features/parameter-untupling-spec.html
 ---
 
-## Motivation
 
-Say you have a list of pairs
-
-```scala
-val xs: List[(Int, Int)]
-```
-
-and you want to map `xs` to a list of `Int`s so that each pair of numbers is mapped to their sum.
-Previously, the best way to do this was with a pattern-matching decomposition:
-
-```scala
-xs.map {
-  case (x, y) => x + y
-}
-```
-While correct, this is inconvenient. Instead, we propose to write it the following way:
-
-```scala
-xs.map {
-  (x, y) => x + y
-}
-```
-
-or, equivalently:
-
-```scala
-xs.map(_ + _)
-```
-
-Generally, a function value with `n > 1` parameters can be converted to a function with tupled arguments if the expected type is a unary function type of the form `((T_1, ..., T_n)) => U`.
 
 ## Type Checking
 

docs/_docs/reference/other-new-features/parameter-untupling.md

@@ -57,12 +57,13 @@ The function value must be explicitly tupled, rather than the parameters untuple
 xs.map(combiner.tupled)
 ```
 
-A conversion may be provided in user code:
+Though strongly discouraged, to have the same effect, an implicit conversion may be provided in user code:
 
 ```scala
 import scala.language.implicitConversions
-transparent inline implicit def `fallback untupling`(f: (Int, Int) => Int): ((Int, Int)) => Int =
-  p => f(p._1, p._2)     // use specialized apply instead of unspecialized `tupled`
+
+transparent inline given `fallback untupling`: Conversion[(Int, Int) => Int, ((Int, Int)) => Int] = _.tupled
+
 xs.map(combiner)
 ```
 

docs/_docs/reference/other-new-features/targetName.md

@@ -93,7 +93,7 @@ The relevant overriding rules can be summarized as follows:
 - If two members override, then both their erased names and their types must be the same.
 
 As usual, any overriding relationship in the generated code must also
-be present in the original code. So the following example would also be in error:
+be present in the original code. So the following example would also be an error:
 
 ```scala
 import annotation.targetName