Merge pull request #10783 from dotty-staging/improve-docs

Update Reference Documentation

Author: nicolasstucki

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

@@ -3,7 +3,7 @@ layout: doc-page
 title: "Changes in Compiler Plugins"
 ---
 
-Compiler plugins are supported by Dotty since 0.9. There are two notable changes
+Compiler plugins are supported by Dotty (and Scala 3) since 0.9. There are two notable changes
 compared to `scalac`:
 
 - No support for analyzer plugins
@@ -13,14 +13,14 @@ compared to `scalac`:
 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, Dotty introduces _research plugin_. Research plugins
+For experimentation and research, Scala 3 introduces _research plugin_. Research plugins
 are more powerful than `scalac` 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 Dotty.
+enabled for nightly or snaphot releases of Scala 3.
 
 Common plugins that add new phases to the compiler pipeline are called
-_standard plugins_ in Dotty. In terms of features, they are similar to
+_standard plugins_ in Scala 3. In terms of features, they are similar to
 `scalac` plugins, despite minor changes in the API.
 
 ## Using Compiler Plugins
@@ -41,7 +41,7 @@ pluginClass=dividezero.DivideZero
 
 This is different from `scalac` plugins that required a `scalac-plugin.xml` file.
 
-Starting from 1.1.5, `sbt` also supports Dotty compiler plugins. Please refer to the
+Starting from 1.1.5, `sbt` also supports Scala 3 compiler plugins. Please refer to the
 `sbt` [documentation][2] for more information.
 
 ## Writing a Standard Compiler Plugin

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

@@ -35,8 +35,7 @@ rather than `next _`.
 The reason for excluding nullary methods from automatic eta expansion
 is that Scala implicitly inserts the `()` argument, which would
 conflict with eta expansion. Automatic `()` insertion is
-[limited](../dropped-features/auto-apply.md) in Dotty, but the fundamental ambiguity
+[limited](../dropped-features/auto-apply.md) in Scala 3, but the fundamental ambiguity
 remains.
 
 [More details](eta-expansion-spec.md)
-

docs/docs/reference/changed-features/implicit-conversions-spec.md

@@ -94,8 +94,8 @@ language:
 ```scala
 implicit val m: Map[Int, String] = Map(1 -> "abc")
 
-val x: String = 1  // scalac: assigns "abc" to x
-                   // Dotty: type error
+val x: String = 1  // Scala 2: assigns "abc" to x
+                   // Scala 3: type error
 ```
 
 This snippet contains a type error. The right hand side of `val x`
@@ -119,4 +119,3 @@ For more information about implicit resolution, see [Changes in
 Implicit Resolution](implicit-resolution.md).
 Other details are available in
 [PR #2065](https://github.com/lampepfl/dotty/pull/2065)
-

docs/docs/reference/changed-features/implicit-resolution.md

@@ -2,7 +2,7 @@
 layout: doc-page
 title: "Changes in Implicit Resolution"
 ---
-This page describes changes to the implicit resolution that apply both to the new `given`s and to the old-style `implicit`s in Dotty.
+This page describes changes to the implicit resolution that apply both to the new `given`s and to the old-style `implicit`s in Scala 3.
 Implicit resolution uses a new algorithm which caches implicit results
 more aggressively for performance. There are also some changes that
 affect implicits on the language level.
@@ -114,7 +114,7 @@ the implicit search for `Q` fails.
 **5.** The treatment of divergence errors has also changed. A divergent implicit is treated as a normal failure, after which alternatives are still tried. This also makes sense: Encountering a divergent implicit means that we assume that no finite solution can be found on the corresponding path, but another path can still be tried. By contrast,
 most (but not all) divergence errors in Scala 2 would terminate the implicit search as a whole.
 
-**6.** Scala-2 gives a lower level of priority to implicit conversions with call-by-name parameters relative to implicit conversions with call-by-value parameters. Dotty drops this distinction. So the following code snippet would be ambiguous in Dotty:
+**6.** Scala-2 gives a lower level of priority to implicit conversions with call-by-name parameters relative to implicit conversions with call-by-value parameters. Scala 3 drops this distinction. So the following code snippet would be ambiguous in Scala 3:
 
 ```scala
   implicit def conv1(x: Int): A = new A(x)

docs/docs/reference/changed-features/interpolation-escapes.md

@@ -5,7 +5,7 @@ title: Escapes in interpolations
 
 In Scala 2 there was no straightforward way to represent a single quote character `"` in a single quoted interpolation. A `\` character can't be used for that because interpolators themselves decide how to handle escaping, so the parser doesn't know whether the `"` should be escaped or used as a terminator.
 
-In Dotty, you can use the `$` meta character of interpolations to escape a `"` character.
+In Scala 3, you can use the `$` meta character of interpolations to escape a `"` character.
 
 ```scala
   val inventor = "Thomas Edison"

docs/docs/reference/changed-features/lazy-vals-init.md

@@ -3,7 +3,7 @@ layout: doc-page
 title: Lazy Vals initialization
 ---
 
-Dotty implements [Version 6](https://docs.scala-lang.org/sips/improved-lazy-val-initialization.html#version-6---no-synchronization-on-this-and-concurrent-initialization-of-fields)
+Scala 3 implements [Version 6](https://docs.scala-lang.org/sips/improved-lazy-val-initialization.html#version-6---no-synchronization-on-this-and-concurrent-initialization-of-fields)
 of the [SIP-20] improved lazy vals initialization proposal.
 
 ## Motivation
@@ -23,7 +23,7 @@ class Foo {
 }
 ```
 
-The Dotty compiler will generate code equivalent to:
+The Scala 3 compiler will generate code equivalent to:
 
 ```scala
 class Foo {

docs/docs/reference/changed-features/overload-resolution.md

@@ -3,7 +3,7 @@ layout: doc-page
 title: "Changes in Overload Resolution"
 ---
 
-Overload resolution in Dotty improves on Scala 2 in two ways.
+Overload resolution in Scala 3 improves on Scala 2 in two ways.
 First, it takes all argument lists into account instead of
 just the first argument list.
 Second, it can infer parameter types of function values even if they
@@ -49,7 +49,7 @@ overload resolution based on additional argument blocks.
 The handling of function values with missing parameter types has been improved. We can now
 pass such values in the first argument list of an overloaded application, provided
 that the remaining parameters suffice for picking a variant of the overloaded function.
-For example, the following code compiles in Dotty, while it results in an
+For example, the following code compiles in Scala 3, while it results in an
 missing parameter type error in Scala2:
 ```scala
 def f(x: Int, f2: Int => Int) = f2(x)

docs/docs/reference/changed-features/pattern-matching.md

@@ -3,9 +3,9 @@ layout: doc-page
 title: "Option-less pattern matching"
 ---
 
-Dotty implementation of pattern matching was greatly simplified compared to Scala 2. From a user perspective, this means that Scala 3 generated patterns are a *lot* easier to debug, as variables all show up in debug modes and positions are correctly preserved.
+The implementation of pattern matching in Scala 3 was greatly simplified compared to Scala 2. From a user perspective, this means that Scala 3 generated patterns are a *lot* easier to debug, as variables all show up in debug modes and positions are correctly preserved.
 
-Dotty supports a superset of Scala 2 [extractors](https://www.scala-lang.org/files/archive/spec/2.13/08-pattern-matching.html#extractor-patterns).
+Scala 3 supports a superset of Scala 2 [extractors](https://www.scala-lang.org/files/archive/spec/2.13/08-pattern-matching.html#extractor-patterns).
 
 ## Extractors
 

docs/docs/reference/contextual/derivation.md

@@ -122,12 +122,12 @@ Mirror.Product {
 Note the following properties of `Mirror` types,
 
 + Properties are encoded using types rather than terms. This means that they have no runtime footprint unless used and
-  also that they are a compile time feature for use with Dotty's metaprogramming facilities.
+  also that they are a compile time feature for use with Scala 3's metaprogramming facilities.
 + The kinds of `MirroredType` and `MirroredElemTypes` match the kind of the data type the mirror is an instance for.
   This allows `Mirrors` to support ADTs of all kinds.
 + There is no distinct representation type for sums or products (ie. there is no `HList` or `Coproduct` type as in
   Scala 2 versions of shapeless). Instead the collection of child types of a data type is represented by an ordinary,
-  possibly parameterized, tuple type. Dotty's metaprogramming facilities can be used to work with these tuple types
+  possibly parameterized, tuple type. Scala 3's metaprogramming facilities can be used to work with these tuple types
   as-is, and higher level libraries can be built on top of them.
 + For both product and sum types, the elements of `MirroredElemTypes` are arranged in definition order (i.e. `Branch[T]`
   precedes `Leaf[T]` in `MirroredElemTypes` for `Tree` because `Branch` is defined before `Leaf` in the source file).
@@ -152,20 +152,20 @@ provider of an ADT with a `derives` clause has to know about the derivation of a
 
 Note that `derived` methods may have context `Mirror` parameters indirectly (e.g. by having a context argument which in turn
 has a context `Mirror` parameter, or not at all (e.g. they might use some completely different user-provided mechanism, for
-instance using Dotty macros or runtime reflection). We expect that (direct or indirect) `Mirror` based implementations
+instance using Scala 3 macros or runtime reflection). We expect that (direct or indirect) `Mirror` based implementations
 will be the most common and that is what this document emphasises.
 
 Type class authors will most likely use higher level derivation or generic programming libraries to implement
 `derived` methods. An example of how a `derived` method might be implemented using _only_ the low level facilities
-described above and Dotty's general metaprogramming features is provided below. It is not anticipated that type class
+described above and Scala 3's general metaprogramming features is provided below. It is not anticipated that type class
 authors would normally implement a `derived` method in this way, however this walkthrough can be taken as a guide for
 authors of the higher level derivation libraries that we expect typical type class authors will use (for a fully
 worked out example of such a library, see [shapeless 3](https://github.com/milessabin/shapeless/tree/shapeless-3)).
 
 #### How to write a type class `derived` method using low level mechanisms
 
 The low-level method we will use to implement a type class `derived` method in this example exploits three new
-type-level constructs in Dotty: inline methods, inline matches, and implicit searches via  `summonInline` or `summonFrom`. Given this definition of the
+type-level constructs in Scala 3: inline methods, inline matches, and implicit searches via  `summonInline` or `summonFrom`. Given this definition of the
 `Eq` type class,
 
 
@@ -194,7 +194,7 @@ call sites (for instance the compiler generated instance definitions in the comp
 
 The body of this method (1) first materializes the `Eq` instances for all the child types of type the instance is
 being derived for. This is either all the branches of a sum type or all the fields of a product type. The
-implementation of `summonAll` is `inline` and uses Dotty's `summonInline` construct to collect the instances as a
+implementation of `summonAll` is `inline` and uses Scala 3's `summonInline` construct to collect the instances as a
 `List`,
 
 ```scala
@@ -319,7 +319,7 @@ given derived$Eq[T](using eqT: Eq[T]): Eq[Opt[T]] =
 ```
 
 Alternative approaches can be taken to the way that `derived` methods can be defined. For example, more aggressively
-inlined variants using Dotty macros, whilst being more involved for type class authors to write than the example
+inlined variants using Scala 3 macros, whilst being more involved for type class authors to write than the example
 above, can produce code for type classes like `Eq` which eliminate all the abstraction artefacts (eg. the `Lists` of
 child instances in the above) and generate code which is indistinguishable from what a programmer might write by hand.
 As a third example, using a higher level library such as shapeless the type class author could define an equivalent
@@ -402,8 +402,8 @@ lockstep and it has to assert this conformance in some places using casts. If ge
 written these casts will never fail.
 
 As mentioned, however, the compiler-provided mechanism is intentionally very low level and it is anticipated that
-higher level type class derivation and generic programming libraries will build on this and Dotty's other
+higher level type class derivation and generic programming libraries will build on this and Scala 3's other
 metaprogramming facilities to hide these low-level details from type class authors and general users. Type class
 derivation in the style of both shapeless and Magnolia are possible (a prototype of shapeless 3, which combines
 aspects of both shapeless 2 and Magnolia has been developed alongside this language feature) as is a more aggressively
-inlined style, supported by Dotty's new quote/splice macro and inlining facilities.
+inlined style, supported by Scala 3's new quote/splice macro and inlining facilities.

docs/docs/reference/contextual/motivation.md

@@ -35,7 +35,7 @@ Particular criticisms are:
     ```
     one cannot write `currentMap("abc")` since the string "abc" is taken as explicit argument to the implicit `ctx` parameter. One has to write `currentMap.apply("abc")` instead, which is awkward and irregular. For the same reason, a method definition can only have one implicit parameter section and it must always come last. This restriction not only reduces orthogonality, but also prevents some useful program constructs, such as a method with a regular parameter whose type depends on an implicit value. Finally, it's also a bit annoying that implicit parameters must have a name, even though in many cases that name is never referenced.
 
- 5. Implicits pose challenges for tooling. The set of available implicits depends on context, so command completion has to take context into account. This is feasible in an IDE but docs like ScalaDoc that are based static web pages can only provide an approximation. Another problem is that failed implicit searches often give very unspecific error messages, in particular if some deeply recursive implicit search has failed. Note that the Dotty compiler has already made a lot of progress in the error diagnostics area. If a recursive search fails some levels down, it shows what was constructed and what is missing. Also, it suggests imports that can bring missing implicits in scope.
+ 5. Implicits pose challenges for tooling. The set of available implicits depends on context, so command completion has to take context into account. This is feasible in an IDE but docs like ScalaDoc that are based static web pages can only provide an approximation. Another problem is that failed implicit searches often give very unspecific error messages, in particular if some deeply recursive implicit search has failed. Note that the Scala 3 compiler has already made a lot of progress in the error diagnostics area. If a recursive search fails some levels down, it shows what was constructed and what is missing. Also, it suggests imports that can bring missing implicits in scope.
 
 None of the shortcomings is fatal, after all implicits are very widely used, and many libraries and applications rely on them. But together, they make code using implicits a lot more cumbersome and less clear than it could be.
 
@@ -78,4 +78,3 @@ Could we achieve the same goals by tweaking existing implicits? After having tri
  - Third, even if we would somehow succeed with migration, we still have the problem
  how to teach this. We cannot make existing tutorials go away. Almost all existing tutorials start with implicit conversions, which will go away; they use normal imports, which will go away, and they explain calls to methods with implicit parameters by expanding them to plain applications, which will also go away. This means that we'd have
  to add modifications and qualifications to all existing literature and courseware, likely causing more confusion with beginners instead of less. By contrast, with a new syntax there is a clear criterion: Any book or courseware that mentions `implicit` is outdated and should be updated.
-

docs/docs/reference/contextual/relationship-implicits.md

@@ -103,7 +103,7 @@ asked for.
 
 Context bounds are the same in both language versions. They expand to the respective forms of implicit parameters.
 
-**Note:** To ease migration, context bounds in Dotty map for a limited time to old-style implicit parameters for which arguments can be passed either in a using clause or
+**Note:** To ease migration, context bounds in Scala 3 map for a limited time to old-style implicit parameters for which arguments can be passed either in a using clause or
 in a normal argument list. Once old-style implicits are deprecated, context bounds
 will map to using clauses instead.
 
@@ -141,7 +141,7 @@ Implicit by-name parameters are not supported in Scala 2, but can be emulated to
 
 ### Implicit Conversions
 
-Implicit conversion methods in Scala 2 can be expressed as given instances of the `scala.Conversion` class in Dotty. E.g. instead of
+Implicit conversion methods in Scala 2 can be expressed as given instances of the `scala.Conversion` class in Scala 3. E.g. instead of
 
 ```scala
 implicit def stringToToken(str: String): Token = new Keyword(str)
@@ -162,18 +162,18 @@ given stringToToken: Conversion[String, Token] = KeyWord(_)
 
 ### Implicit Classes
 
-Implicit classes in Scala 2 are often used to define extension methods, which are directly supported in Dotty. Other uses of implicit classes can be simulated by a pair of a regular class and a given `Conversion` instance.
+Implicit classes in Scala 2 are often used to define extension methods, which are directly supported in Scala 3. Other uses of implicit classes can be simulated by a pair of a regular class and a given `Conversion` instance.
 
 ### Implicit Values
 
-Implicit `val` definitions in Scala 2 can be expressed in Dotty using a regular `val` definition and an alias given.
+Implicit `val` definitions in Scala 2 can be expressed in Scala 3 using a regular `val` definition and an alias given.
 E.g., Scala 2's
 
 ```scala
 lazy implicit val pos: Position = tree.sourcePos
 ```
 
-can be expressed in Dotty as
+can be expressed in Scala 3 as
 
 ```scala
 lazy val pos: Position = tree.sourcePos
@@ -182,13 +182,13 @@ given Position = pos
 
 ### Abstract Implicits
 
-An abstract implicit `val` or `def` in Scala 2 can be expressed in Dotty using a regular abstract definition and an alias given. E.g., Scala 2's
+An abstract implicit `val` or `def` in Scala 2 can be expressed in Scala 3 using a regular abstract definition and an alias given. E.g., Scala 2's
 
 ```scala
 implicit def symDecorator: SymDecorator
 ```
 
-can be expressed in Dotty as
+can be expressed in Scala 3 as
 
 ```scala
 def symDecorator: SymDecorator
@@ -197,7 +197,7 @@ given SymDecorator = symDecorator
 
 ## Implementation Status and Timeline
 
-The Dotty implementation implements both Scala-2's implicits and the new abstractions. In fact, support for Scala-2's implicits is an essential part of the common language subset between 2.13/2.14 and Dotty.
+The Scala 3 implementation implements both Scala-2's implicits and the new abstractions. In fact, support for Scala-2's implicits is an essential part of the common language subset between 2.13/2.14 and Scala 3.
 Migration to the new abstractions will be supported by making automatic rewritings available.
 
 Depending on adoption patterns, old style implicits might start to be deprecated in a version following Scala 3.0.