Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs/reference] more fixes in Markdown files #10875

Merged
merged 4 commits into from
Dec 24, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ val x: String = 1 // Scala 2: assigns "abc" to x
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
will report a type error, because `Map` isn't an instance of
`Conversion`.

## Migration path
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/reference/changed-features/operators.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
layout: doc-page
title: Rules for Operators
title: "Rules for Operators"
---

The rules for infix operators have changed in some parts:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ The standard library defines a universal marker trait `Selectable` in the packag
trait Selectable extends Any
```

An implementation of `Selectable` that relies on Java reflection is
An implementation of `Selectable` that relies on [Java reflection](https://www.oracle.com/technical-resources/articles/java/javareflection.html) is
available in the standard library: `scala.reflect.Selectable`. Other
implementations can be envisioned for platforms where Java reflection
is not available.
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/reference/changed-features/structural-types.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ Besides `selectDynamic`, a `Selectable` class sometimes also defines a method `a

## Using Java Reflection

Structural types can also be accessed using Java reflection. Example:
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 }

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/reference/changed-features/vararg-patterns.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ The change to the grammar is:

## Compatibility considerations

To enable smooth cross compilation between Scala 2 and Scala 3, Dotty will
To enable smooth cross compilation between Scala 2 and Scala 3, the compiler will
accept both the old and the new syntax. Under the `-source 3.1` setting, an error
will be emitted when the old syntax is encountered. They will be enabled by
default in version 3.1 of the language.
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/reference/contextual/derivation-macro.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ check we want to generate is the following:
&& Eq[Int].eqv(x.productElement(1), y.productElement(1))
```

### Calling the derived method inside the macro
## Calling the derived method inside the macro

Following the rules in [Macros](../metaprogramming/toc.md) we create two methods.
One that hosts the top-level splice `eqv` and one that is the implementation.
Expand Down
31 changes: 17 additions & 14 deletions docs/docs/reference/contextual/derivation.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,13 +59,13 @@ sealed trait Mirror:

object Mirror:

/** The Mirror for a product type */
trait Product extends Mirror:
/** The Mirror for a product type */
trait Product extends Mirror:

/** Create a new instance of type `T` with elements
* taken from product `p`.
*/
def fromProduct(p: scala.Product): MirroredMonoType
/** Create a new instance of type `T` with elements
* taken from product `p`.
*/
def fromProduct(p: scala.Product): MirroredMonoType

trait Sum extends Mirror:

Expand Down Expand Up @@ -125,12 +125,12 @@ Note the following properties of `Mirror` types,
+ 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,
Scala 2 versions of Shapeless). Instead the collection of child types of a data type is represented by an ordinary,
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).
This means that `Mirror.Sum` differs in this respect from shapeless's generic representation for ADTs in Scala 2,
This means that `Mirror.Sum` differs in this respect from Shapeless's generic representation for ADTs in Scala 2,
where the constructors are ordered alphabetically by name.
+ The methods `ordinal` and `fromProduct` are defined in terms of `MirroredMonoType` which is the type of kind-`*`
which is obtained from `MirroredType` by wildcarding its type parameters.
Expand Down Expand Up @@ -159,7 +159,7 @@ Type class authors will most likely use higher level derivation or generic progr
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)).
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

Expand Down Expand Up @@ -307,7 +307,7 @@ Alternative approaches can be taken to the way that `derived` methods can be def
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
As a third example, using a higher level library such as Shapeless the type class author could define an equivalent
`derived` method as,

```scala
Expand All @@ -317,9 +317,12 @@ given eqSum[A](using inst: => K0.CoproductInstances[Eq, A]): Eq[A] with

given eqProduct[A](using inst: K0.ProductInstances[Eq, A]): Eq[A] with
def eqv(x: A, y: A): Boolean = inst.foldLeft2(x, y)(true: Boolean)(
[t] => (acc: Boolean, eqt: Eq[t], t0: t, t1: t) => Complete(!eqt.eqv(t0, t1))(false)(true)
[t] => (acc: Boolean, eqt: Eq[t], t0: t, t1: t) =>
Complete(!eqt.eqv(t0, t1))(false)(true)
)

inline def derived[A](using gen: K0.Generic[A]) as Eq[A] = gen.derive(eqSum, eqProduct)
inline def derived[A](using gen: K0.Generic[A]) as Eq[A] =
gen.derive(eqSum, eqProduct)
```

The framework described here enables all three of these approaches without mandating any of them.
Expand Down Expand Up @@ -385,6 +388,6 @@ 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 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
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 Scala 3's new quote/splice macro and inlining facilities.
1 change: 1 addition & 0 deletions docs/docs/reference/contextual/given-imports.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,7 @@ import Instances.{im, given Ordering[?]}
```

would import `im`, `intOrd`, and `listOrd` but leave out `ec`.

### Migration

The rules for imports stated above have the consequence that a library
Expand Down
8 changes: 5 additions & 3 deletions docs/docs/reference/contextual/motivation.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ title: "Overview"
Scala's implicits are its most distinguished feature. They are _the_ fundamental way to abstract over context. They represent a unified paradigm with a great variety of use cases, among them: implementing type classes, establishing context, dependency injection, expressing capabilities, computing new types and proving relationships between them.

Following Haskell, Scala was the second popular language to have some form of implicits. Other languages have followed suit. E.g [Rust's traits](https://doc.rust-lang.org/rust-by-example/trait.html) or [Swift's protocol extensions](https://docs.swift.org/swift-book/LanguageGuide/Protocols.html#ID521). Design proposals are also on the table for Kotlin as [compile time dependency resolution](https://github.com/Kotlin/KEEP/blob/e863b25f8b3f2e9b9aaac361c6ee52be31453ee0/proposals/compile-time-dependency-resolution.md), for C# as [Shapes and Extensions](https://github.com/dotnet/csharplang/issues/164)
or for F# as [Traits](https://github.com/MattWindsor91/visualfsharp/blob/hackathon-vs/examples/fsconcepts.md). Implicits are also a common feature of theorem provers such as Coq or [Agda](https://agda.readthedocs.io/en/latest/language/implicit-arguments.html).
or for F# as [Traits](https://github.com/MattWindsor91/visualfsharp/blob/hackathon-vs/examples/fsconcepts.md). Implicits are also a common feature of theorem provers such as [Coq](https://coq.inria.fr/refman/language/extensions/implicit-arguments.html) or [Agda](https://agda.readthedocs.io/en/latest/language/implicit-arguments.html).

Even though these designs use widely different terminology, they are all variants of the core idea of _term inference_. Given a type, the compiler synthesizes a "canonical" term that has that type. Scala embodies the idea in a purer form than most other languages: An implicit parameter directly leads to an inferred argument term that could also be written down explicitly. By contrast, type class based designs are less direct since they hide term inference behind some form of type classification and do not offer the option of writing the inferred quantities (typically, dictionaries) explicitly.

Expand All @@ -30,12 +30,14 @@ Particular criticisms are:
3. The syntax of implicit definitions is too minimal. It consists of a single modifier, `implicit`, that can be attached to a large number of language constructs. A problem with this for newcomers is that it conveys mechanism instead of intent. For instance, a type class instance is an implicit object or val if unconditional and an implicit def with implicit parameters referring to some class if conditional. This describes precisely what the implicit definitions translate to -- just drop the `implicit` modifier, and that's it! But the cues that define intent are rather indirect and can be easily misread, as demonstrated by the definitions of `i1` and `i2` above.

4. The syntax of implicit parameters also has shortcomings. While implicit _parameters_ are designated specifically, arguments are not. Passing an argument to an implicit parameter looks like a regular application `f(arg)`. This is problematic because it means there can be confusion regarding what parameter gets instantiated in a call. For instance, in

```scala
def currentMap(implicit ctx: Context): Map[String, Int]
```
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 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.
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 tools like [Scaladoc](https://docs.scala-lang.org/overviews/scaladoc/overview.html) that are based on 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.

Expand Down
3 changes: 2 additions & 1 deletion docs/docs/reference/contextual/multiversal-equality.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,8 @@ class Box[T](x: T) derives CanEqual
By the usual rules of [type class derivation](./derivation.md),
this generates the following `CanEqual` instance in the companion object of `Box`:
```scala
given [T, U](using CanEqual[T, U]): CanEqual[Box[T], Box[U]] = CanEqual.derived
given [T, U](using CanEqual[T, U]): CanEqual[Box[T], Box[U]] =
CanEqual.derived
```
That is, two boxes are comparable with `==` or `!=` if their elements are. Examples:
```scala
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/reference/contextual/relationship-implicits.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ mirroring the definition syntax. E.g, `max(2, 3)(using IntOrd)`.
Scala 2 uses normal applications `max(2, 3)(IntOrd)` instead. The Scala 2 syntax has some inherent ambiguities and restrictions which are overcome by the new syntax. For instance, multiple implicit parameter lists are not available in the old syntax, even though they can be simulated using auxiliary objects in the "Aux" pattern.

The `summon` method corresponds to `implicitly` in Scala 2.
It is precisely the same as the `the` method in Shapeless.
It is precisely the same as the `the` method in [Shapeless](https://github.com/milessabin/shapeless).
The difference between `summon` (or `the`) and `implicitly` is
that `summon` can return a more precise type than the type that was
asked for.
Expand Down Expand Up @@ -129,7 +129,7 @@ Abstract extension methods in traits that are implemented in given instances hav

### Type Class Derivation

Type class derivation has no direct counterpart in the Scala 2 language. Comparable functionality can be achieved by macro-based libraries such as Shapeless, Magnolia, or scalaz-deriving.
Type class derivation has no direct counterpart in the Scala 2 language. Comparable functionality can be achieved by macro-based libraries such as [Shapeless](https://github.com/milessabin/shapeless), [Magnolia](https://propensive.com/opensource/magnolia), or [scalaz-deriving](https://github.com/scalaz/scalaz-deriving).

### Context Function Types

Expand Down
11 changes: 6 additions & 5 deletions docs/docs/reference/enums/desugarEnums.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ some terminology and notational conventions:

The desugaring rules imply that class cases are mapped to case classes, and singleton cases are mapped to `val` definitions.

There are nine desugaring rules. Rule (1) desugar enum definitions. Rules
There are nine desugaring rules. Rule (1) desugars enum definitions. Rules
(2) and (3) desugar simple cases. Rules (4) to (6) define `extends` clauses for cases that
are missing them. Rules (7) to (9) define how such cases with `extends` clauses
map into `case class`es or `val`s.
Expand Down Expand Up @@ -176,10 +176,11 @@ If `E` contains at least one simple case, its companion object will define in ad
follows.

```scala
private def $new(_$ordinal: Int, $name: String) = new E with runtime.EnumValue:
def ordinal = _$ordinal
override def productPrefix = $name // if not overridden in `E`
override def toString = $name // if not overridden in `E`
private def $new(_$ordinal: Int, $name: String) =
new E with runtime.EnumValue:
def ordinal = _$ordinal
override def productPrefix = $name // if not overridden in `E`
override def toString = $name // if not overridden in `E`
```

The anonymous class also implements the abstract `Product` methods that it inherits from `Enum`.
Expand Down
6 changes: 3 additions & 3 deletions docs/docs/reference/enums/enums.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ The companion object of an enum also defines three utility methods.
The `valueOf` method obtains an enum value
by its name. The `values` method returns all enum values
defined in an enumeration in an `Array`. The `fromOrdinal`
method obtains an enum value from its ordinal (Int) value.
method obtains an enum value from its ordinal (`Int`) value.

```scala
scala> Color.valueOf("Blue")
Expand All @@ -63,7 +63,7 @@ It is possible to add your own definitions to an enum. Example:
enum Planet(mass: Double, radius: Double):
private final val G = 6.67300E-11
def surfaceGravity = G * mass / (radius * radius)
def surfaceWeight(otherMass: Double) = otherMass * surfaceGravity
def surfaceWeight(otherMass: Double) = otherMass * surfaceGravity

case Mercury extends Planet(3.303e+23, 2.4397e6)
case Venus extends Planet(4.869e+24, 6.0518e6)
Expand All @@ -72,7 +72,7 @@ enum Planet(mass: Double, radius: Double):
case Jupiter extends Planet(1.9e+27, 7.1492e7)
case Saturn extends Planet(5.688e+26, 6.0268e7)
case Uranus extends Planet(8.686e+25, 2.5559e7)
case Neptune extends Planet(1.024e+26, 2.4746e7)
case Neptune extends Planet(1.024e+26, 2.4746e7)
end Planet
```

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/reference/features-classification.md
Original file line number Diff line number Diff line change
Expand Up @@ -162,7 +162,7 @@ Being new features, existing code migrates without changes. To be sure, sometime

## Metaprogramming

The following constructs together aim to put metaprogramming in Scala on a new basis. So far, metaprogramming was achieved by a combination of macros and libraries such as Shapeless that were in turn based on some key macros. Current Scala 2 macro mechanisms are a thin veneer on top the current Scala 2 compiler, which makes them fragile and in many cases impossible to port to Scala 3.
The following constructs together aim to put metaprogramming in Scala on a new basis. So far, metaprogramming was achieved by a combination of macros and libraries such as [Shapeless](https://github.com/milessabin/shapeless) that were in turn based on some key macros. Current Scala 2 macro mechanisms are a thin veneer on top the current Scala 2 compiler, which makes them fragile and in many cases impossible to port to Scala 3.

It's worth noting that macros were never included in the Scala 2 language specification and were so far made available only under an `-experimental` flag. This has not prevented their widespread usage.

Expand Down
2 changes: 0 additions & 2 deletions docs/docs/reference/metaprogramming/erased-terms-spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@ layout: doc-page
title: "Erased Terms Spec"
---

# Implementation

## Rules

1. The `erased` modifier can appear:
Expand Down
Loading