Merge pull request #14191 from michelou/scala3-docs

more updates to Markdown files

Author: anatoliykmetyuk

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

@@ -12,7 +12,7 @@ defined by either:
 - An `implicit def` which has type `S => T` or `(=> S) => T`
 - An implicit value which has type `Conversion[S, T]`
 
-The standard library defines an abstract class `Conversion`:
+The standard library defines an abstract class [`Conversion`](https://scala-lang.org/api/3.x/scala/Conversion.html):
 
 ```scala
 package scala
@@ -86,7 +86,7 @@ Note that implicit conversions are also affected by the [changes to implicit res
 
 ## Motivation for the changes
 
-The introduction of [`scala.Conversion`](https://github.com/lampepfl/dotty/blob/master/library/src/scala/Conversion.scala)
+The introduction of [`scala.Conversion`](https://scala-lang.org/api/3.x/scala/Conversion.html)
 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:
@@ -102,7 +102,7 @@ This snippet contains a type error. The right-hand side of `val x`
 does not conform to type `String`. In Scala 2, the compiler will use
 `m` as an implicit conversion from `Int` to `String`, whereas Scala 3
 will report a type error, because `Map` isn't an instance of
-`Conversion`.
+[`Conversion`](https://scala-lang.org/api/3.x/scala/Conversion.html).
 
 ## Migration path
 

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

@@ -28,9 +28,10 @@ Defining an implicit conversion will emit a warning unless the import
 
 ## Examples
 
-The first example is taken from `scala.Predef`. Thanks to this
-implicit conversion, it is possible to pass a `scala.Int` to a Java
-method that expects a `java.lang.Integer`
+The first example is taken from [`scala.Predef`](https://scala-lang.org/api/3.x/scala/Predef$.html).
+Thanks to this implicit conversion, it is possible to pass a
+[`scala.Int`](https://scala-lang.org/api/3.x/scala/Int.html)
+to a Java method that expects a `java.lang.Integer`
 
 ```scala
 import scala.language.implicitConversions

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

@@ -110,7 +110,7 @@ which means that the alternative `c` would be chosen as solution!
 Scala 2's somewhat puzzling behavior with respect to ambiguity has been exploited to implement
 the analogue of a "negated" search in implicit resolution, where a query `Q1` fails if some
 other query `Q2` succeeds and `Q1` succeeds if `Q2` fails. With the new cleaned up behavior
-these techniques no longer work. But there is now a new special type `scala.util.NotGiven`
+these techniques no longer work. But there is now a new special type [`scala.util.NotGiven`](https://scala-lang.org/api/3.x/scala/util/NotGiven.html)
 which implements negation directly. For any query type `Q`, `NotGiven[Q]` succeeds if and only if
 the implicit search for `Q` fails.
 

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

@@ -4,7 +4,7 @@ title: "Escapes in interpolations"
 movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/interpolation-escapes.html
 ---
 
-In Scala 2 there is 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 Scala 2 there is 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 `"` character should be escaped or used as a terminator.
 
 In Scala 3, we can use the `$` meta character of interpolations to escape a `"` character. Example:
 

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

@@ -5,7 +5,7 @@ movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/main-func
 ---
 
 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.
+A [`@main`](https://scala-lang.org/api/3.x/scala/main.html) annotation on a method turns this method into an executable program.
 Example:
 
 ```scala
@@ -31,13 +31,11 @@ This would generate a main program `happyBirthday` that could be called like thi
 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.CommandLineParser.FromString` type class
-that is used to convert an argument string to the required parameter type.
-The parameter list of a main method can end in a repeated parameter that then
-takes all remaining arguments given on the command line.
+A [`@main`](https://scala-lang.org/api/3.x/scala/main.html) 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`](https://scala-lang.org/api/3.x/scala/main.html) method can have an arbitrary number of parameters.
+For each parameter type there must be an instance of the [`scala.util.CommandLineParser.FromString[T]`](https://scala-lang.org/api/3.x/scala/util/CommandLineParser$$FromString.html) type class that is used to convert an argument string to the required parameter type `T`.
+The parameter list of a main method can end in a repeated parameter that then takes all remaining arguments given on the command line.
 
-The program implemented from a `@main` method checks that there are enough arguments on
+The program implemented from a [`@main`](https://scala-lang.org/api/3.x/scala/main.html) method checks that there are enough arguments on
 the command line to fill in all parameters, and that argument strings are convertible to
 the required types. If a check fails, the program is terminated with an error message.
 
@@ -51,11 +49,11 @@ Illegal command line after first argument: more arguments expected
 Illegal command line: java.lang.NumberFormatException: For input string: "sixty"
 ```
 
-The Scala compiler generates a program from a `@main` method `f` as follows:
+The Scala compiler generates a program from a [`@main`](https://scala-lang.org/api/3.x/scala/main.html) method `f` as follows:
 
- - It creates a class named `f` in the package where the `@main` method was found
+ - It creates a class named `f` in the package where the [`@main`](https://scala-lang.org/api/3.x/scala/main.html) method was found
  - The class has a static method `main` with the usual signature. It takes an `Array[String]`
-   as argument and returns `Unit`.
+   as argument and returns [`Unit`](https://scala-lang.org/api/3.x/scala/Unit.html).
  - The generated `main` method calls method `f` with arguments converted using
    methods in the [`scala.util.CommandLineParser`](https://scala-lang.org/api/3.x/scala/util/CommandLineParser$.html) object.
 
@@ -77,13 +75,13 @@ final class happyBirthday:
 **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` 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:
+[`@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:
 
 ```scala
 object happyBirthday extends App:
   // needs by-hand parsing of arguments vector
   ...
 ```
 
-The previous functionality of `App`, which relied on the "magic" [`DelayedInit`](../dropped-features/delayed-init.md) trait, is no longer available. [`App`](https://scala-lang.org/api/3.x/scala/App.md) 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`](https://www.scala-lang.org/api/3.x/scala/App.html), which relied on the "magic" [`DelayedInit`](../dropped-features/delayed-init.md) trait, is no longer available. [`App`](https://scala-lang.org/api/3.x/scala/App.html) 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/pattern-bindings.md

@@ -21,12 +21,11 @@ This code gives a compile-time warning in Scala 3.1 (and also in Scala 3.0 under
 val pair = (1, true)
 val (x, y) = pair
 ```
-Sometimes one wants to decompose data anyway, even though the pattern is refutable. For instance, if at some point one knows that a list `elems` is non-empty one might
-want to decompose it like this:
+Sometimes one wants to decompose data anyway, even though the pattern is refutable. For instance, if at some point one knows that a list `elems` is non-empty one might want to decompose it like this:
 ```scala
 val first :: rest = elems   // error
 ```
-This works in Scala 2. In fact it is a typical use case for Scala 2's rules. But in Scala 3.1 it will give a warning. One can avoid the warning by marking the right-hand side with an `@unchecked` annotation:
+This works in Scala 2. In fact it is a typical use case for Scala 2's rules. But in Scala 3.1 it will give a warning. One can avoid the warning by marking the right-hand side with an [`@unchecked`](https://scala-lang.org/api/3.x/scala/unchecked.html) annotation:
 ```scala
 val first :: rest = elems: @unchecked   // OK
 ```

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

@@ -59,7 +59,7 @@ help from the user. In practice, the connection between a structural type
 and its underlying generic representation would most likely be done by
 a database layer, and therefore would not be a concern of the end user.
 
-`Record` extends the marker trait `scala.Selectable` and defines
+`Record` extends the marker trait [`scala.Selectable`](https://scala-lang.org/api/3.x/scala/Selectable.html) and defines
 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
@@ -90,7 +90,7 @@ Structural types can also be accessed using [Java reflection](https://www.oracle
     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
+Here, we define a structural type `Closeable` that defines a `close` method. There are various classes that have `close` methods, we just list [`FileInputStream`](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/io/FileInputStream.html#%3Cinit%3E(java.io.File)) and [`Channel`](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/channels/Channel.html) 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
@@ -147,10 +147,9 @@ 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.
+is implemented by the base trait [`reflect.Selectable`](https://scala-lang.org/api/3.x/scala/reflect/Selectable.html) 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:
+`Vehicle` could also extend some other subclass of [`scala.Selectable`](https://scala-lang.org/api/3.x/scala/Selectable.html) 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:
@@ -168,25 +167,25 @@ adding any refinements. Hence, `i3` now has just type `Vehicle` and the selectio
 
 Note that in Scala 2 all local and anonymous classes could produce values with refined types. But
 members defined by such refinements could be selected only with the language import
-`reflectiveCalls`.
+[`reflectiveCalls`](https://scala-lang.org/api/3.x/scala/languageFeature$$reflectiveCalls$.html).
 
 ## Relation with `scala.Dynamic`
 
-There are clearly some connections with `scala.Dynamic` here, since
+There are clearly some connections with [`scala.Dynamic`](https://scala-lang.org/api/3.x/scala/Dynamic.html) here, since
 both select members programmatically. But there are also some
 differences.
 
 - Fully dynamic selection is not typesafe, but structural selection
   is, as long as the correspondence of the structural type with the
   underlying value is as stated.
 
-- `Dynamic` is just a marker trait, which gives more leeway where and
+- [`Dynamic`](https://scala-lang.org/api/3.x/scala/Dynamic.html) is just a marker trait, which gives more leeway where and
   how to define reflective access operations. By contrast
   `Selectable` is a trait which declares the access operations.
 
 - Two access operations, `selectDynamic` and `applyDynamic` are shared
   between both approaches. In `Selectable`, `applyDynamic` also may also take
-  `java.lang.Class` arguments indicating the method's formal parameter types.
-  `Dynamic` comes with `updateDynamic`.
+  [`java.lang.Class`](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Class.html) arguments indicating the method's formal parameter types.
+  [`Dynamic`](https://scala-lang.org/api/3.x/scala/Dynamic.html) comes with `updateDynamic`.
 
 [More details](structural-types-spec.md)

docs/docs/reference/contextual/context-functions-spec.md

@@ -1,7 +1,6 @@
 ---
 layout: doc-page
 title: "Context Functions - More Details"
-
 movedTo: https://docs.scala-lang.org/scala3/reference/contextual/context-functions-spec.html
 ---
 
@@ -64,7 +63,7 @@ Context function literals `(x1: T1, ..., xn: Tn) ?=> e` are
 automatically created for any expression `e` whose expected type is
 `scala.ContextFunctionN[T1, ..., Tn, R]`, unless `e` is
 itself a context function literal. This is analogous to the automatic
-insertion of `scala.Function0` around expressions in by-name argument position.
+insertion of [`scala.Function0`](https://scala-lang.org/api/3.x/scala/Function0.html) around expressions in by-name argument position.
 
 Context function types generalize to `N > 22` in the same way that function types do, see [the corresponding
 documentation](../dropped-features/limit22.md).

docs/docs/reference/contextual/givens.md

@@ -120,9 +120,9 @@ In each case, a pattern-bound given instance consists of `given` and a type `T`.
 
 Scala 2's somewhat puzzling behavior with respect to ambiguity has been exploited to implement the analogue of a "negated" search in implicit resolution,
 where a query Q1 fails if some other query Q2 succeeds and Q1 succeeds if Q2 fails. With the new cleaned up behavior these techniques no longer work.
-But the new special type `scala.util.NotGiven` now implements negation directly.
+But the new special type [`scala.util.NotGiven`](https://scala-lang.org/api/3.x/scala/util/NotGiven.html) now implements negation directly.
 
-For any query type `Q`, `NotGiven[Q]` succeeds if and only if the implicit
+For any query type `Q`, [`NotGiven[Q]`](https://scala-lang.org/api/3.x/scala/util/NotGiven.html) succeeds if and only if the implicit
 search for `Q` fails, for example:
 
 ```scala

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

@@ -4,9 +4,11 @@ title: "Dropped: DelayedInit"
 movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/delayed-init.html
 ---
 
-The special handling of the `DelayedInit` trait is no longer supported.
+The special handling of the [`DelayedInit`](https://scala-lang.org/api/3.x/scala/DelayedInit.html)
+trait is no longer supported.
 
-One consequence is that the `App` class, which used `DelayedInit` is
+One consequence is that the [`App`](https://scala-lang.org/api/3.x/scala/App.html) class,
+which used [`DelayedInit`](https://scala-lang.org/api/3.x/scala/DelayedInit.html) is
 now partially broken. You can still use `App` as a simple way to set up a main program. Example:
 
 ```scala