Tweaks

Author: odersky

docs/docs/reference/contextual/motivation.md

@@ -5,12 +5,12 @@ title: "Overview"
 
 ### Critique of the Status Quo
 
-Scala's implicits are its most distinguished feature. They are _the_ fundamental way to abstract over context. They represent a unified paradigm with an extremely varied number of use cases, among them: implementing type classes, establishing context, dependency injection, expressing capabilities, computing new types and proving relationships between them.
+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 probably the second popular language to have some form of implicits. Other languages have followed suit. E.g Rust's traits or Swift's protocol extensions. 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)
+Following Haskell, Scala was the second popular language to have some form of implicits. Other languages have followed suit. E.g Rust's traits or Swift's protocol extensions. 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.
 
-Even though all 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, typeclass 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 explicitly.
+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, typeclass 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.
 
 Given that term inference is where the industry is heading, and given that Scala has it in a very pure form, how come implicits are not more popular? In fact, it's fair to say that implicits are at the same time Scala's most distinguished and most controversial feature. I believe this is due to a number of aspects that together make implicits harder to learn than necessary and also make it harder to prevent abuses.
 
@@ -39,22 +39,23 @@ Particular criticisms are:
 
 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.
 
+Historically, many of these shortcomings come from the way implicits were gradually "discovered" in Scala. Scala originally had only implicit conversions with the intended use case of "extending" a class or trait after it was defined, i.e. what is expressed by implicit classes in later versions of Scala. Implicit parameters and instance definitions came later in 2006 and picked similar syntax since it seemed convenient. For the same reason, no effort was made to distinguish implicit imports or arguments from normal ones.
+
 Existing Scala programmers by and large have gotten used to the status quo and see little need for change. But for newcomers this status quo presents a big hurdle. I believe if we want to overcome that hurdle, we should take a step back and allow ourselves to consider a radically new design.
 
 ### The New Design
 
-The following pages introduce a redesign of contextual abstractions in Scala. They introduce the following new constructs:
+The following pages introduce a redesign of contextual abstractions in Scala. They introduce four fundamental new constructs:
 
- 1. A way to replace implicit _definitions_ by [implied instance definitions](./instance-defs.html). The core principle of the proposal is that, rather than
- mixing the `implicit` modifier with a large number of features, we have a single way to define terms that can be synthesized for types.
+ 1. [Implied Instances](./instance-defs.html) are a new way to define inferable terms.  They replace implicit definitions. The core principle of the proposal is that, rather than mixing the `implicit` modifier with a large number of features, we have a single way to define terms that can be synthesized for types.
 
- 2. A [new syntax](./inferable-params.html) for implicit _parameters_ and their _arguments_. Both are introduced with the same keyword, `given`. This unambiguously aligns parameters and arguments, solving a number of language warts. It also allows us to have several implicit parameter sections, and to have implicit parameters followed by normal ones.
+ 2. [Inferable Parameters](./inferable-params.html) are a new syntax for implicit _parameters_ and their _arguments_. Both are introduced with the same keyword, `given`. This unambiguously aligns parameters and arguments, solving a number of language warts. It also allows us to have several implicit parameter sections, and to have implicit parameters followed by normal ones.
 
- 3. A new form of import, [import implied](./import-implied.html) that specifically imports implicit definitions and nothing else. New-style implicit definitions _must be_ imported with  `import implied`, a plain import will no longer bring them into scope.
+ 3. [Implied Imports](./import-implied.html) are new form of import that specifically imports implicit definitions and nothing else. New-style implicit definitions _must be_ imported with  `import implied`, a plain import will no longer bring them into scope.
 
- 4. A new way to write [implicit conversions](./conversions.html) as implied instances of a `Conversion` class. All other forms of implicit conversions will be phased out.
+ 4. [Implicit Conversions](./conversions.html) are now expressed as implied instances of a standard `Conversion` class. All other forms of implicit conversions will be phased out.
 
-This section also contains pages describing other language features that are related to context abstraction.  These are:
+This section also contains pages describing other language features that are related to context abstraction. These are:
 
  - [Context Bounds](./context-bounds.html), which carry over unchanged.
  - [Extension Methods](./extension-methods.html) replace implicit classes in a way that integrates better with typeclasses.
@@ -72,9 +73,9 @@ This design thus avoids feature interactions and makes the language more consist
 
 Could we achieve the same goals by tweaking existing implicits? After having tried for a long time, I believe now that this is impossible.
 
- - First, some of the problems are clearly syntactic and require different syntax to solve.
- - Second, there is the problem how to migrate. We cannot change the rules in mid-flight. At some stage of language evolution we need to accommodate both the new and the old rules. With a syntax change, this is easy: Introduce the new syntax with new rules, support the old syntax for a while to facilitate cross compilation, deprecate and phase out the old syntax some times later. Keeping the same syntax does not offer this path, and in fact does not seem to offer any viable path for evolution
+ - First, some of the problems are clearly syntactic and require different syntax to solve them.
+ - Second, there is the problem how to migrate. We cannot change the rules in mid-flight. At some stage of language evolution we need to accommodate both the new and the old rules. With a syntax change, this is easy: Introduce the new syntax with new rules, support the old syntax for a while to facilitate cross compilation, deprecate and phase out the old syntax at some later time. Keeping the same syntax does not offer this path, and in fact does not seem to offer any viable path for evolution
  - Third, even if we would somehow succeed with migration, we still have the problem
  how to teach this. We cannot make existing tutorials go away. Almost all existing tutorials start with implicit conversions, which will go away; they use normal imports, which will go away, and they explain calls to methods with implicit parameters by expanding them to plain applications, which will also go away. This means that we'd have
- to add modifications and qualifications to all existing literature and courseware,likely causing more confusion with beginners instead of less. By contrast, with a new syntax there is a clear criterion: Any courseware that mentions `implicit` is outdated and should be replaced.
+ to add modifications and qualifications to all existing literature and courseware, likely causing more confusion with beginners instead of less. By contrast, with a new syntax there is a clear criterion: Any courseware that mentions `implicit` is outdated and should be replaced.