Merge pull request #10953 from michelou/scala3-docs

[docs/reference] more fixes in Markdown files

Author: liufengyun

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

@@ -73,4 +73,4 @@ The method value syntax `m _` is deprecated.
 
 ## Reference
 
-For more info, see [PR #2701](https://github.com/lampepfl/dotty/pull/2701).
+For more information, see [PR #2701](https://github.com/lampepfl/dotty/pull/2701).

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

@@ -119,4 +119,4 @@ Resolution](implicit-resolution.md) for more information.
 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)
+[PR #2065](https://github.com/lampepfl/dotty/pull/2065).

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

@@ -6,6 +6,7 @@ title: "Main Methods"
 Scala 3 offers a new way to define programs that can be invoked from the command line:
 A `@main` annotation on a method turns this method into an executable program.
 Example:
+
 ```scala
 @main def happyBirthday(age: Int, name: String, others: String*) =
    val suffix =
@@ -21,11 +22,14 @@ Example:
    for other <- others do bldr.append(" and ").append(other)
    bldr.toString
 ```
+
 This would generate a main program `happyBirthday` that could be called like this
+
 ```
 > scala happyBirthday 23 Lisa Peter
 Happy 23rd Birthday, Lisa and Peter!
 ```
+
 A `@main` annotated method can be written either at the top-level or in a statically accessible object. The name of the program is in each case the name of the method, without any object prefixes. The `@main` method can have an arbitrary number of parameters.
 For each parameter type there must be an instance of the `scala.util.FromString` type class
 that is used to convert an argument string to the required parameter type.
@@ -52,9 +56,10 @@ The Scala compiler generates a program from a `@main` method `f` as follows:
  - The class has a static method `main` with the usual signature. It takes an `Array[String]`
    as argument and returns `Unit`.
  - The generated `main` method calls method `f` with arguments converted using
-   methods in the `scala.util.CommandLineParser` object.
+   methods in the [`scala.util.CommandLineParser` object](https://dotty.epfl.ch/api/scala/util/CommandLineParser$.html).
 
 For instance, the `happyBirthDay` method above would generate additional code equivalent to the following class:
+
 ```scala
 final class happyBirthday:
    import scala.util.{CommandLineParser => CLP}
@@ -67,6 +72,7 @@ final class happyBirthday:
       catch
          case error: CLP.ParseError => CLP.showError(error)
 ```
+
 **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.
 
@@ -78,5 +84,5 @@ object happyBirthday extends App:
    ...
 ```
 
-The previous functionality of `App`, which relied on the "magic" `DelayedInit` trait, is no longer available. `App` still exists in limited form for now, but it does not support command line arguments and will be deprecated in the future. If programs need to cross-build
+The previous functionality of `App`, which relied on the "magic" [`DelayedInit`](../dropped-features/delayed-init.md) trait, is no longer available. `App` still exists in limited form for now, but it does not support command line arguments and will be deprecated in the future. If programs need to cross-build
 between Scala 2 and Scala 3, it is recommended to use an explicit `main` method with an `Array[String]` argument instead.

docs/docs/reference/changed-features/match-syntax.md

@@ -1,6 +1,6 @@
 ---
 layout: doc-page
-title: Match Expressions
+title: "Match Expressions"
 ---
 
 The syntactical precedence of match expressions has been changed.

docs/docs/reference/changed-features/numeric-literals.md

@@ -1,14 +1,16 @@
 ---
 layout: doc-page
-title: Numeric Literals
+title: "Numeric Literals"
 ---
 
 **Note**: 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
 ```
 
-In Scala 2, numeric literals were confined to the primitive numeric types `Int`, `Long`, `Float`, and `Double`. Scala 3 allows to write numeric literals also for user defined types. Example:
+In Scala 2, numeric literals were confined to the primitive numeric types `Int`, `Long`, `Float`, and `Double`. Scala 3 allows to write numeric literals also for user-defined types. Example:
+
 ```scala
 val x: Long = -10_000_000_000
 val y: BigInt = 0x123_abc_789_def_345_678_901
@@ -17,6 +19,7 @@ val z: BigDecimal = 110_222_799_799.99
 (y: BigInt) match
    case 123_456_789_012_345_678_901 =>
 ```
+
 The syntax of numeric literals is the same as before, except there are no pre-set limits
 how large they can be.
 

docs/docs/reference/changed-features/operators.md

@@ -12,6 +12,7 @@ a syntax change allows infix operators to be written on the left in a multi-line
 ## The `infix` Modifier
 
 An `infix` modifier on a method definition allows using the method as an infix operation. Example:
+
 ```scala
 import scala.annotation.targetName
 
@@ -40,6 +41,7 @@ s1 * s2             // OK
 s1 `*` s2           // also OK, but unusual
 s1.*(s2)            // also OK, but unusual
 ```
+
 Infix operations involving alphanumeric operators are deprecated, unless
 one of the following conditions holds:
 
@@ -53,7 +55,8 @@ any Unicode character `c` for which `java.lang.Character.isIdentifierPart(c)` re
 Infix operations involving symbolic operators are always allowed, so `infix` is redundant for methods with symbolic names.
 
 The `infix` modifier can also be given to a type:
-```
+
+```scala
 infix type or[X, Y]
 val x: String or Int = ...
 ```
@@ -107,6 +110,7 @@ It is recommended that definitions of symbolic operators carry a [`@targetName`
 ## Syntax Change
 
 Infix operators can now appear at the start of lines in a multi-line expression. Examples:
+
 ```scala
 val str = "hello"
    ++ " world"
@@ -117,6 +121,7 @@ def condition =
    || xs.exists(_ > 0)
    || xs.isEmpty
 ```
+
 Previously, those expressions would have been rejected, since the compiler's semicolon inference
 would have treated the continuations `++ " world"` or `|| xs.isEmpty` as separate statements.
 
@@ -133,19 +138,24 @@ Example:
     freezing
   | boiling
 ```
+
 This is recognized as a single infix operation. Compare with:
+
 ```scala
     freezing
   !boiling
 ```
+
 This is seen as two statements, `freezing` and `!boiling`. The difference is that only the operator in the first example
 is followed by a space.
 
 Another example:
+
 ```scala
   println("hello")
   ???
   ??? match { case 0 => 1 }
 ```
+
 This code is recognized as three different statements. `???` is syntactically a symbolic identifier, but
 neither of its occurrences is followed by a space and a token that can start an expression.

docs/docs/reference/changed-features/structural-types-spec.md

@@ -30,9 +30,11 @@ the methods `selectDynamic` and `applyDynamic`. The methods could be members of
 
 The `selectDynamic` method takes a field name and returns the value associated with that name in the `Selectable`.
 It should have a signature of the form:
+
 ```scala
 def selectDynamic(name: String): T
 ```
+
 Often, the return type `T` is `Any`.
 
 Unlike `scala.Dynamic`, there is no special meaning for an `updateDynamic` method.
@@ -41,10 +43,12 @@ Consequently, it is recommended not to define any member called `updateDynamic`
 
 The `applyDynamic` method is used for selections that are applied to arguments. It takes a method name and possibly `Class`es representing its parameters types as well as the arguments to pass to the function.
 Its signature should be of one of the two following forms:
+
 ```scala
 def applyDynamic(name: String)(args: Any*): T
 def applyDynamic(name: String, ctags: Class[?]*)(args: Any*): T
 ```
+
 Both versions are passed the actual arguments in the `args` parameter. The second version takes in addition a vararg argument of `java.lang.Class`es that identify the method's parameter classes. Such an argument is needed
 if `applyDynamic` is implemented using Java reflection, but it could be
 useful in other cases as well. `selectDynamic` and `applyDynamic` can also take additional context parameters in using clauses. These are resolved in the normal way at the callsite.
@@ -94,5 +98,4 @@ conversion that can turn `v` into a `Selectable`, and the selection methods coul
 
 ## Context
 
-For more info, see [Rethink Structural
-Types](https://github.com/lampepfl/dotty/issues/1886).
+For more information, see [Rethink Structural Types](https://github.com/lampepfl/dotty/issues/1886).

docs/docs/reference/changed-features/structural-types.md

@@ -32,19 +32,23 @@ configure how fields and methods should be resolved.
 ## Example
 
 Here's an example of a structural type `Person`:
+
 ```scala
   class Record(elems: (String, Any)*) extends Selectable:
      private val fields = elems.toMap
      def selectDynamic(name: String): Any = fields(name)
 
   type Person = Record { val name: String; val age: Int }
  ```
+ 
 The type `Person` adds a _refinement_ to its parent type `Record` that defines the two fields `name` and `age`. We say the refinement is _structural_ since  `name` and `age` are not defined in the parent type. But they exist nevertheless as members of class `Person`. For instance, the following
 program would print  "Emma is 42 years old.":
+
 ```scala
   val person = Record("name" -> "Emma", "age" -> 42).asInstanceOf[Person]
   println(s"${person.name} is ${person.age} years old.")
 ```
+
 The parent type `Record` in this example is a generic class that can represent arbitrary records in its `elems` argument. This argument is a
 sequence of pairs of labels of type `String` and values of type `Any`.
 When we create a `Person` as a `Record` we have to assert with a typecast
@@ -59,19 +63,22 @@ a method `selectDynamic`, which maps a field name to its value.
 Selecting a structural type member is done by calling this method.
 The `person.name` and `person.age` selections are translated by
 the Scala compiler to:
+
 ```scala
   person.selectDynamic("name").asInstanceOf[String]
   person.selectDynamic("age").asInstanceOf[Int]
 ```
 
 Besides `selectDynamic`, a `Selectable` class sometimes also defines a method `applyDynamic`. This can then be used to translate function calls of structural members. So, if `a` is an instance of `Selectable`, a structural call like `a.f(b, c)` would translate to
+
 ```scala
   a.applyDynamic("f")(b, c)
 ```
 
 ## Using Java Reflection
 
 Structural types can also be accessed using [Java reflection](https://www.oracle.com/technical-resources/articles/java/javareflection.html). Example:
+
 ```scala
   type Closeable = { def close(): Unit }
 
@@ -81,14 +88,17 @@ Structural types can also be accessed using [Java reflection](https://www.oracle
   class Channel:
     def close(): Unit
 ```
+
 Here, we define a structural type `Closeable` that defines a `close` method. There are various classes that have `close` methods, we just list `FileInputStream` and `Channel` as two examples. It would be easiest if the two classes shared a common interface that factors out the `close` method. But such factorings are often not possible if different libraries are combined in one application. Yet, we can still have methods that work on
 all classes with a `close` method by using the `Closeable` type. For instance,
+
 ```scala
   import scala.reflect.Selectable.reflectiveSelectable
 
   def autoClose(f: Closeable)(op: Closeable => Unit): Unit =
     try op(f) finally f.close()
 ```
+
 The call `f.close()` has to use Java reflection to identify and call the `close` method in the receiver `f`. This needs to be enabled by an import
 of `reflectiveSelectable` shown above. What happens "under the hood" is then the following:
 
@@ -122,6 +132,7 @@ the database access example given at the beginning of this document.
 
 Local and anonymous classes that extend `Selectable` get more refined types
 than other classes. Here is an example:
+
 ```scala
 trait Vehicle extends reflect.Selectable:
    val wheels: Int
@@ -132,12 +143,14 @@ val i3 = new Vehicle: // i3: Vehicle { val range: Int }
 
 i3.range
 ```
+
 The type of `i3` in this example is `Vehicle { val range: Int }`. Hence,
 `i3.range` is well-formed. Since the base class `Vehicle` does not define a `range` field or method, we need structural dispatch to access the `range` field of the anonymous class that initializes `id3`. Structural dispatch
 is implemented by the base trait `reflect.Selectable` of `Vehicle`, which
 defines the necessary `selectDynamic` member.
 
 `Vehicle` could also extend some other subclass of `scala.Selectable` that implements `selectDynamic` and `applyDynamic` differently. But if it does not extend a `Selectable` at all, the code would no longer typecheck:
+
 ```scala
 trait Vehicle:
    val wheels: Int
@@ -148,6 +161,7 @@ val i3 = new Vehicle: // i3: Vehicle
 
 i3.range // error: range is not a member of `Vehicle`
 ```
+
 The difference is that the type of an anonymous class that does not extend `Selectable` is just formed from the parent type(s) of the class, without
 adding any refinements. Hence, `i3` now has just type `Vehicle` and the selection `i3.range` gives a "member not found" error.
 

docs/docs/reference/changed-features/type-checking.md

@@ -3,4 +3,4 @@ layout: doc-page
 title: "Changes in Type Checking"
 ---
 
-[//]: # todo: fill in
+*** **TO BE FILLED IN** ***

docs/docs/reference/changed-features/type-inference.md

@@ -3,4 +3,7 @@ layout: doc-page
 title: "Changes in Type Inference"
 ---
 
-See https://www.youtube.com/watch?v=lMvOykNQ4zs, https://www.youtube.com/watch?v=VV9lPg3fNl8.
+For more information, see the two presentations
+
+* [Scala 3, Type inference and You!](https://www.youtube.com/watch?v=lMvOykNQ4zs) by Guillaume Martres (September 2019)
+* [GADTs in Dotty](https://www.youtube.com/watch?v=VV9lPg3fNl8) by Aleksander Boruch-Gruszecki (July 2019).

docs/docs/reference/changed-features/wildcards.md

@@ -17,7 +17,8 @@ for the type lambda `[X] =>> C[X]`. This makes higher-kinded types easier to use
 parameter, `F[_]` means `F` is a type constructor whereas used as a type, `F[_]` means it is a wildcard (i.e. existential) type.
 In the future, `F[_]` will mean the same thing, no matter where it is used.
 
-We pick `?` as a replacement syntax for wildcard types, since it aligns with Java's syntax.
+We pick `?` as a replacement syntax for wildcard types, since it aligns with
+[Java's syntax](https://docs.oracle.com/javase/tutorial/java/generics/wildcardGuidelines.html).
 
 ### Migration Strategy
 
@@ -40,4 +41,4 @@ option `-Ykind-projector`:
     available to rewrite one to the other.
  3. In Scala 3.3, `*` is removed again, and all type parameter placeholders will be expressed with `_`.
 
-These rules make it possible to cross build between Scala 2 using the kind projector plugin and Scala 3.0 - 3.2 using option `-Ykind-projector`.
+These rules make it possible to cross build between Scala 2 using the kind projector plugin and Scala 3.0 - 3.2 using the compiler option `-Ykind-projector`.

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

@@ -35,6 +35,7 @@ The precise steps for synthesizing an argument for a by-name context parameter o
     ```scala
     given lv: T = ???
     ```
+
     where `lv` is an arbitrary fresh name.
 
  1. This given is not immediately available as candidate for argument inference (making it immediately available could result in a loop in the synthesized computation). But it becomes available in all nested contexts that look again for an argument to a by-name context parameter.
@@ -51,13 +52,13 @@ 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)
+   optionCodec[Int](using intCodec)
 )
 ```
 
 No local given instance was generated because the synthesized argument is not recursive.
 
 ### Reference
 
-For more info, see [Issue #1998](https://github.com/lampepfl/dotty/issues/1998)
+For more information, see [Issue #1998](https://github.com/lampepfl/dotty/issues/1998)
 and the associated [Scala SIP](https://docs.scala-lang.org/sips/byname-implicits.html).