Skip to content

Commit 1803076

Browse files
authored
Merge pull request #11334 from ShapelessCat/fix-docs-overview
Fix the overview of the documentation
2 parents 03c01c1 + e1560c9 commit 1803076

File tree

1 file changed

+82
-65
lines changed

1 file changed

+82
-65
lines changed

docs/docs/reference/overview.md

Lines changed: 82 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -9,12 +9,13 @@ In this reference, we discuss design decisions and present important differences
99

1010
The language redesign was guided by three main goals:
1111

12-
- Strengthen Scala's foundations.
13-
Make the full programming language compatible with the foundational work on the
14-
[DOT calculus](https://infoscience.epfl.ch/record/227176/files/soundness_oopsla16.pdf)
15-
and apply the lessons learned from that work.
16-
- Make Scala easier and safer to use. Tame powerful constructs such as implicits to provide a gentler learning curve. Remove warts and puzzlers.
17-
- Further improve the consistency and expressiveness of Scala's language constructs.
12+
- Strengthen Scala's foundations.
13+
Make the full programming language compatible with the foundational work on the
14+
[DOT calculus](https://infoscience.epfl.ch/record/227176/files/soundness_oopsla16.pdf)
15+
and apply the lessons learned from that work.
16+
- Make Scala easier and safer to use.
17+
Tame powerful constructs such as implicits to provide a gentler learning curve. Remove warts and puzzlers.
18+
- Further improve the consistency and expressiveness of Scala's language constructs.
1819

1920
Corresponding to these goals, the language changes fall into seven categories:
2021
(1) Core constructs to strengthen foundations, (2) simplifications and (3) [restrictions](#restrictions), to make the language easier and safer to use, (4) dropped constructs to make the language smaller and more regular, (5) [changed constructs](#changes) to remove warts, and increase consistency and usability, (6) [new constructs](#new-constructs) to fill gaps and increase expressiveness, (7) a new, principled approach to metaprogramming that replaces [Scala 2 experimental macros](https://docs.scala-lang.org/overviews/macros/overview.html).
@@ -23,30 +24,35 @@ Corresponding to these goals, the language changes fall into seven categories:
2324

2425
These new constructs directly model core features of DOT, higher-kinded types, and the [SI calculus for implicit resolution](https://infoscience.epfl.ch/record/229878/files/simplicitly_1.pdf).
2526

26-
- [Intersection types](new-types/intersection-types.md), replacing compound types,
27-
- [Union types](new-types/union-types.md),
28-
- [Type lambdas](new-types/type-lambdas.md), replacing encodings using structural types and type projection.
29-
- [Context functions](contextual/context-functions.md), offering abstraction over given parameters.
27+
- [Intersection types](new-types/intersection-types.md), replacing compound types,
28+
- [Union types](new-types/union-types.md),
29+
- [Type lambdas](new-types/type-lambdas.md), replacing encodings using structural types and type projection.
30+
- [Context functions](contextual/context-functions.md), offering abstraction over given parameters.
3031

3132
## Simplifications
3233

3334
These constructs replace existing constructs with the aim of making the language safer and simpler to use, and to promote uniformity in code style.
3435

35-
- [Trait parameters](other-new-features/trait-parameters.md) replace [early initializers](dropped-features/early-initializers.md) with a more generally useful construct.
36-
- [Given instances](contextual/givens.md)
37-
replace implicit objects and defs, focussing on intent over mechanism.
38-
- [Using clauses](contextual/using-clauses.md) replace implicit parameters, avoiding their ambiguities.
39-
- [Extension methods](contextual/extension-methods.md) replace implicit classes with a clearer and simpler mechanism.
40-
- [Opaque type aliases](other-new-features/opaques.md) replace most uses
41-
of value classes while guaranteeing absence of boxing.
42-
- [Top-level definitions](dropped-features/package-objects.md) replace package objects, dropping syntactic boilerplate.
43-
- [Export clauses](other-new-features/export.md)
44-
provide a simple and general way to express aggregation, which can replace the
45-
previous facade pattern of package objects inheriting from classes.
46-
- [Vararg patterns](changed-features/vararg-patterns.md) now use the form `: _*` instead of `@ _*`, mirroring vararg expressions,
47-
- [Creator applications](other-new-features/creator-applications.md) allow using simple function call syntax
48-
instead of `new` expressions. `new` expressions stay around as a fallback for
49-
the cases where creator applications cannot be used.
36+
- [Trait parameters](other-new-features/trait-parameters.md)
37+
replace [early initializers](dropped-features/early-initializers.md) with a more generally useful construct.
38+
- [Given instances](contextual/givens.md)
39+
replace implicit objects and defs, focussing on intent over mechanism.
40+
- [Using clauses](contextual/using-clauses.md)
41+
replace implicit parameters, avoiding their ambiguities.
42+
- [Extension methods](contextual/extension-methods.md)
43+
replace implicit classes with a clearer and simpler mechanism.
44+
- [Opaque type aliases](other-new-features/opaques.md)
45+
replace most uses of value classes while guaranteeing absence of boxing.
46+
- [Top-level definitions](dropped-features/package-objects.md)
47+
replace package objects, dropping syntactic boilerplate.
48+
- [Export clauses](other-new-features/export.md)
49+
provide a simple and general way to express aggregation, which can replace
50+
the previous facade pattern of package objects inheriting from classes.
51+
- [Vararg splices](changed-features/vararg-splices.md)
52+
now use the form `xs*` in function arguments and patterns instead of `xs: _*` and `xs @ _*`,
53+
- [Universal apply methods](other-new-features/creator-applications.md)
54+
allow using simple function call syntax instead of `new` expressions. `new` expressions stay around
55+
as a fallback for the cases where creator applications cannot be used.
5056

5157
With the exception of [early initializers](dropped-features/early-initializers.md) and old-style vararg patterns, all superseded constructs continue to be available in Scala 3.0. The plan is to deprecate and phase them out later.
5258

@@ -56,62 +62,69 @@ Value classes (superseded by opaque type aliases) are a special case. There are
5662

5763
These constructs are restricted to make the language safer.
5864

59-
- [Implicit Conversions](contextual/conversions.md): there is only one way to define implicit conversions instead of many, and potentially surprising implicit conversions require a language import.
60-
- [Given Imports](contextual/given-imports.md): implicits now require a special form of import, to make the import clearly visible.
61-
- [Type Projection](dropped-features/type-projection.md): only classes can be used as prefix `C` of a type projection `C#A`. Type projection on abstract types is no longer supported since it is unsound.
62-
- [Multiversal Equality](contextual/multiversal-equality.md) implements an "opt-in" scheme to rule out nonsensical comparisons with `==` and `!=`.
63-
- [infix](changed-features/operators.md)
64-
make method application syntax uniform across code bases.
65+
- [Implicit Conversions](contextual/conversions.md):
66+
there is only one way to define implicit conversions instead of many, and potentially surprising implicit conversions require a language import.
67+
- [Given Imports](contextual/given-imports.md):
68+
implicits now require a special form of import, to make the import clearly visible.
69+
- [Type Projection](dropped-features/type-projection.md):
70+
only classes can be used as prefix `C` of a type projection `C#A`. Type projection on abstract types is no longer supported since it is unsound.
71+
- [Multiversal Equality](contextual/multiversal-equality.md):
72+
implement an "opt-in" scheme to rule out nonsensical comparisons with `==` and `!=`.
73+
- [infix](changed-features/operators.md):
74+
make method application syntax uniform across code bases.
6575

6676
Unrestricted implicit conversions continue to be available in Scala 3.0, but will be deprecated and removed later. Unrestricted versions of the other constructs in the list above are available only under `-source 3.0-migration`.
6777

68-
6978
## Dropped Constructs
7079

7180
These constructs are proposed to be dropped without a new construct replacing them. The motivation for dropping these constructs is to simplify the language and its implementation.
7281

73-
- [DelayedInit](dropped-features/delayed-init.md),
74-
- [Existential types](dropped-features/existential-types.md),
75-
- [Procedure syntax](dropped-features/procedure-syntax.md),
76-
- [Class shadowing](dropped-features/class-shadowing.md),
77-
- [XML literals](dropped-features/xml.md),
78-
- [Symbol literals](dropped-features/symlits.md),
79-
- [Auto application](dropped-features/auto-apply.md),
80-
- [Weak conformance](dropped-features/weak-conformance.md),
81-
- [Compound types](new-types/intersection-types.md),
82-
- [Auto tupling](https://github.com/lampepfl/dotty/pull/4311) (implemented, but not merged).
82+
- [DelayedInit](dropped-features/delayed-init.md),
83+
- [Existential types](dropped-features/existential-types.md),
84+
- [Procedure syntax](dropped-features/procedure-syntax.md),
85+
- [Class shadowing](dropped-features/class-shadowing.md),
86+
- [XML literals](dropped-features/xml.md),
87+
- [Symbol literals](dropped-features/symlits.md),
88+
- [Auto application](dropped-features/auto-apply.md),
89+
- [Weak conformance](dropped-features/weak-conformance.md),
90+
- [Compound types](new-types/intersection-types.md) (replaced by [Intersection types](new-types/intersection-types.md)),
91+
- [Auto tupling](https://github.com/lampepfl/dotty/pull/4311) (implemented, but not merged).
8392

8493
The date when these constructs are dropped varies. The current status is:
8594

86-
- Not implemented at all:
87-
- DelayedInit, existential types, weak conformance.
88-
- Supported under `-source 3.0-migration`:
89-
- procedure syntax, class shadowing, symbol literals, auto application, auto tupling in a restricted form.
90-
- Supported in 3.0, to be deprecated and phased out later:
91-
- [XML literals](dropped-features/xml.md), compound types.
92-
95+
- Not implemented at all:
96+
- DelayedInit, existential types, weak conformance.
97+
- Supported under `-source 3.0-migration`:
98+
- procedure syntax, class shadowing, symbol literals, auto application, auto tupling in a restricted form.
99+
- Supported in 3.0, to be deprecated and phased out later:
100+
- [XML literals](dropped-features/xml.md), compound types.
93101

94102
## Changes
95103

96104
These constructs have undergone changes to make them more regular and useful.
97105

98-
- [Structural Types](changed-features/structural-types.md): They now allow pluggable implementations, which greatly increases their usefulness. Some usage patterns are restricted compared to the status quo.
99-
- [Name-based pattern matching](changed-features/pattern-matching.md): The existing undocumented Scala 2 implementation has been codified in a slightly simplified form.
100-
- [Eta expansion](changed-features/eta-expansion.md) is now performed universally also in the absence of an expected type. The postfix `_` operator is thus made redundant. It will be deprecated and dropped after Scala 3.0.
101-
- [Implicit Resolution](changed-features/implicit-resolution.md): The implicit resolution rules have been cleaned up to make them more useful and less surprising. Implicit scope is restricted to no longer include package prefixes.
106+
- [Structural Types](changed-features/structural-types.md):
107+
They now allow pluggable implementations, which greatly increases their usefulness. Some usage patterns are restricted compared to the status quo.
108+
- [Name-based pattern matching](changed-features/pattern-matching.md):
109+
The existing undocumented Scala 2 implementation has been codified in a slightly simplified form.
110+
- [Automatic Eta expansion](changed-features/eta-expansion.md):
111+
Eta expansion is now performed universally also in the absence of an expected type. The postfix `_` operator is thus made redundant. It will be deprecated and dropped after Scala 3.0.
112+
- [Implicit Resolution](changed-features/implicit-resolution.md):
113+
The implicit resolution rules have been cleaned up to make them more useful and less surprising. Implicit scope is restricted to no longer include package prefixes.
102114

103115
Most aspects of old-style implicit resolution are still available under `-source 3.0-migration`. The other changes in this list are applied unconditionally.
104116

105117
## New Constructs
106118

107119
These are additions to the language that make it more powerful or pleasant to use.
108120

109-
- [Enums](enums/enums.md) provide concise syntax for enumerations and [algebraic data types](enums/adts.md).
110-
- [Parameter untupling](other-new-features/parameter-untupling.md) avoids having to use `case` for tupled parameter destructuring.
111-
- [Dependent function types](new-types/dependent-function-types.md) generalize dependent methods to dependent function values and types.
112-
- [Polymorphic function types](new-types/polymorphic-function-types.md) generalize polymorphic methods to polymorphic function values and types. _Current status_: There is a proposal and a merged prototype implementation, but the implementation has not been finalized (it is notably missing type inference support).
113-
- [Kind polymorphism](other-new-features/kind-polymorphism.md) allows the definition of operators working equally on types and type constructors.
114-
- [`@targetName` annotations](other-new-features/targetName.md) make it easier to interoperate with code written in other languages and give more flexibility for avoiding name clashes.
121+
- [Enums](enums/enums.md) provide concise syntax for enumerations and [algebraic data types](enums/adts.md).
122+
- [Parameter untupling](other-new-features/parameter-untupling.md) avoids having to use `case` for tupled parameter destructuring.
123+
- [Dependent function types](new-types/dependent-function-types.md) generalize dependent methods to dependent function values and types.
124+
- [Polymorphic function types](new-types/polymorphic-function-types.md) generalize polymorphic methods to polymorphic function values and types.
125+
_Current status_: There is a proposal and a merged prototype implementation, but the implementation has not been finalized (it is notably missing type inference support).
126+
- [Kind polymorphism](other-new-features/kind-polymorphism.md) allows the definition of operators working equally on types and type constructors.
127+
- [`@targetName` annotations](other-new-features/targetName.md) make it easier to interoperate with code written in other languages and give more flexibility for avoiding name clashes.
115128

116129
## Metaprogramming
117130

@@ -121,12 +134,16 @@ It's worth noting that macros were never included in the [Scala 2 language speci
121134

122135
To enable porting most uses of macros, we are experimenting with the advanced language constructs listed below. These designs are more provisional than the rest of the proposed language constructs for Scala 3.0. There might still be some changes until the final release. Stabilizing the feature set needed for metaprogramming is our first priority.
123136

124-
- [Match Types](new-types/match-types.md) allow computation on types.
125-
- [Inline](metaprogramming/inline.md) provides
126-
by itself a straightforward implementation of some simple macros and is at the same time an essential building block for the implementation of complex macros.
127-
- [Quotes and Splices](metaprogramming/macros.md) provide a principled way to express macros and staging with a unified set of abstractions.
128-
- [Type class derivation](contextual/derivation.md) provides an in-language implementation of the `Gen` macro in Shapeless and other foundational libraries. The new implementation is more robust, efficient and easier to use than the macro.
129-
- [Implicit by-name parameters](contextual/by-name-context-parameters.md) provide a more robust in-language implementation of the `Lazy` macro in [Shapeless](https://github.com/milessabin/shapeless).
137+
- [Match Types](new-types/match-types.md)
138+
allow computation on types.
139+
- [Inline](metaprogramming/inline.md)
140+
provides by itself a straightforward implementation of some simple macros and is at the same time an essential building block for the implementation of complex macros.
141+
- [Quotes and Splices](metaprogramming/macros.md)
142+
provide a principled way to express macros and staging with a unified set of abstractions.
143+
- [Type class derivation](contextual/derivation.md)
144+
provides an in-language implementation of the `Gen` macro in Shapeless and other foundational libraries. The new implementation is more robust, efficient and easier to use than the macro.
145+
- [By-name context parameters](contextual/by-name-context-parameters.md)
146+
provide a more robust in-language implementation of the `Lazy` macro in [Shapeless](https://github.com/milessabin/shapeless).
130147

131148
## See Also
132149

0 commit comments

Comments
 (0)