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

docs/docs/reference/dropped-features/package-objects.md

@@ -11,7 +11,7 @@ package object p {
   def b = ...
 }
 ```
-will be dropped. They are still available in Scala 3.0, but will be deprecated and removed afterwards.
+will be dropped. They are still available in Scala 3.0 and 3.1, but will be deprecated and removed afterwards.
 
 Package objects are no longer needed since all kinds of definitions can now be written at the top-level. Example:
 ```scala

docs/docs/reference/dropped-features/symlits.md

@@ -6,5 +6,19 @@ movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/symlits.h
 
 Symbol literals are no longer supported.
 
-The `scala.Symbol` class still exists, so a
-literal translation of the symbol literal `'xyz` is `Symbol("xyz")`. However, it is recommended to use a plain string literal `"xyz"` instead. (The `Symbol` class will be deprecated and removed in the future).
+The [`scala.Symbol`](https://scala-lang.org/api/3.x/scala/Symbol.html) class still exists, so a literal translation of the symbol literal `'xyz` is `Symbol("xyz")`. However, it is recommended to use a plain string literal `"xyz"` instead. (The `Symbol` class will be deprecated and removed in the future). Example:
+
+
+```
+scalac Test.scala
+-- Error: Test.scala:1:25 ------------------------------------------------------------------------------------------------
+
+1 |@main def test = println('abc)
+  |                         ^
+  |                         symbol literal 'abc is no longer supported,
+  |                         use a string literal "abc" or an application Symbol("abc") instead,
+  |                         or enclose in braces '{abc} if you want a quoted expression.
+  |                         For now, you can also `import language.deprecated.symbolLiterals` to accept
+  |                         the idiom, but this possibility might no longer be available in the future.
+1 error found
+```