Improve documentation

asakaev · asakaev · commit a56ddf50a619 · 2020-05-25T00:39:19.000+03:00
diff --git a/.github/ISSUE_TEMPLATE/crash.md b/.github/ISSUE_TEMPLATE/crash.md
@@ -1,6 +1,6 @@
 ---
 name: "\U0001F4A5 Crash report"
-about: Report a Dotty Compiler compiler crash
+about: Report a Dotty compiler crash
 title: ''
 labels: itype:bug, itype:crash
 assignees: ''
diff --git a/docs/blog/_posts/2016-02-03-essence-of-scala.md b/docs/blog/_posts/2016-02-03-essence-of-scala.md
@@ -65,7 +65,7 @@ property was shown with a mechanized, (i.e. machine-checked) proof:
 Formulating the precise soundness theorem and proving it was unexpectedly hard,
 because it uncovered some technical challenges that had not been
 studied in depth before. In DOT - as well as in many programming languages -
-you can have conflicting definitions. For instance you might have an abstract
+you can have conflicting definitions. For instance, you might have an abstract
 type declaration in a base class with two conflicting aliases in subclasses:
 ```scala
 trait Base { type A }
@@ -142,4 +142,4 @@ project are important.
     This lets us put other constructs of the Scala language to the test,
     either to increase our confidence that they are indeed sound, or
     to show that they are unsound. In my next blog I will
-    present some of the issues we have discovered through that exercise.
+    present some issues we have discovered through that exercise.
diff --git a/docs/blog/_posts/2016-05-05-multiversal-equality.md b/docs/blog/_posts/2016-05-05-multiversal-equality.md
@@ -18,7 +18,7 @@ For instance, one might want to introduce a proxy for some data structure so tha
 
 ## Where Are We Today?
 
-The problems of universal equality in Scala are of course well known. Some libraries have tried to fix it by adding another equality operator with more restricted typing. Most often this safer equality is written `===`. While `===` is certainly useful, I am not a fan of adding another equality operator to the language and core libraries. It would be much better if we could fix `==` instead. This would be both simpler and would catch all potential equality problems including those related to pattern matching.
+The problems of universal equality in Scala are of course well-known. Some libraries have tried to fix it by adding another equality operator with more restricted typing. Most often this safer equality is written `===`. While `===` is certainly useful, I am not a fan of adding another equality operator to the language and core libraries. It would be much better if we could fix `==` instead. This would be both simpler and would catch all potential equality problems including those related to pattern matching.
 
 How can `==` be fixed? It looks much harder to do this than adding an alternate equality operator. First, we have to keep backwards compatibility. The ability to compare everything to everything is by now baked into lots of code and libraries.  Second, with just one equality operator we need to make this operator work in all cases where it makes sense. An alternative `===` operator can choose to refuse some comparisons that should be valid because there's always `==` to fall back to. With a unique `==` operator we do not have this luxury.
 
diff --git a/docs/blog/_posts/2016-12-05-implicit-function-types.md b/docs/blog/_posts/2016-12-05-implicit-function-types.md
@@ -14,7 +14,7 @@ abstraction to Scala_". What do I mean by this?
 **Abstraction**: The ability to name a concept and use just the name afterwards.
 
 **Contextual**: A piece of a program produces results or outputs in
-some context. Our programming languages are very good in describing
+some context. Our programming languages are very good at describing
 and abstracting what outputs are produced. But there's hardly anything
 yet available to abstract over the inputs that programs get from their
 context. Many interesting scenarios fall into that category,
diff --git a/docs/blog/_posts/2017-12-01-fifth-dotty-milestone-release.md b/docs/blog/_posts/2017-12-01-fifth-dotty-milestone-release.md
@@ -109,7 +109,7 @@ are currently two backends using the TASTY frontend:
    different backends...
 
 ### Generic java signatures [#3234](https://github.com/lampepfl/dotty/pull/3234)
-Dotty now emits generic signatures for classes and methods. Theses signatures are used by compilers,
+Dotty now emits generic signatures for classes and methods. Those signatures are used by compilers,
 debuggers and to support runtime reflection. For example:
 
 ```scala
diff --git a/docs/blog/_posts/2019-04-15-14th-dotty-milestone-release.md b/docs/blog/_posts/2019-04-15-14th-dotty-milestone-release.md
@@ -122,7 +122,7 @@ For more information, please see the [documentation](https://dotty.epfl.ch/docs/
 
 ## Other changes
 
-Some of the other changes include:
+Some other changes include:
 
 - `infer` method renamed to `the`, the semantics of which is now the same as that of the `the` method of Shapeless. Namely, the implicits are resolved more precisely – see this [gist](https://gist.github.com/milessabin/8833a1dbf7e8245b30f8) for an example in Shapeless, and the Dotty [documentation](https://dotty.epfl.ch/docs/reference/contextual/given-clauses.html#querying-implied-instances) for more details.
 - The syntax of quoting and splicing was changed. Now the quoting is expressed via `'{ ... }` and `'[...]` and splicing – via `${...}` and `$id`. Please see the [documentation](https://dotty.epfl.ch/docs/reference/metaprogramming/macros.html) for more details on these features.
diff --git a/docs/blog/_posts/2019-05-23-15th-dotty-milestone-release.md b/docs/blog/_posts/2019-05-23-15th-dotty-milestone-release.md
@@ -83,7 +83,7 @@ val res3: Int = 3
 
 To smoothen the migration, the deprecation warnings will only be emitted if you compile with the `-strict` flag under Scala 3. Alphanumeric methods that are defined without the `@infix` annotation used in an infix position will be deprecated by default starting with Scala 3.1.
 
-For more information, see the the [documentation](https://dotty.epfl.ch/docs/reference/changed-features/operators.html#the-infix-annotation). Note that the `@alpha` annotation also described in the documentation is planned for the future and is not available in this release.
+For more information, see the [documentation](https://dotty.epfl.ch/docs/reference/changed-features/operators.html#the-infix-annotation). Note that the `@alpha` annotation also described in the documentation is planned for the future and is not available in this release.
 
 ## `given` clause comes last
 In the previous release, you could write something like this:
@@ -167,7 +167,7 @@ def eval[T](e: Expr[T]): T = e match {
 We've also plugged a few soundness problems (e.g. [#5667](https://github.com/lampepfl/dotty/issues/5667)) caused by inferring too much when matching on abstract, union and intersection types. For more information, see PR [#5736](https://github.com/lampepfl/dotty/pull/5736).
 
 ## Other changes
-Some of the other notable changes include the following:
+Some other notable changes include the following:
 
 - Singletons are now allowed in union types. E.g. the following is allowed: `object foo; type X = Int | foo.type`.
 - A bunch of improvements was made for the type inference system – see, e.g., PRs [#6454](https://github.com/lampepfl/dotty/pull/6454) and [#6467](https://github.com/lampepfl/dotty/pull/6467).
diff --git a/docs/blog/_posts/2019-11-04-20th-dotty-milestone-release.md b/docs/blog/_posts/2019-11-04-20th-dotty-milestone-release.md
@@ -59,7 +59,7 @@ The main reasons for dropping `private[this]` are:
 - Its effect over `private` is purely local and can be easily inferred.
 - It leads to bike shedding: should I use `private` or `private[this]`? One is shorter but the other might be more efficient.
 
-`protected[this]` by now influences compiler decisions in no way at all. Hence it is is reasonable to drop it.
+`protected[this]` by now influences compiler decisions in no way at all. Hence it is reasonable to drop it.
 
 ## `with` keyword's new role
 `with` keyword can now optionally precede the class body. So that you can write your classes as follows:
diff --git a/docs/blog/_posts/2019-12-20-21th-dotty-milestone-release.md b/docs/blog/_posts/2019-12-20-21th-dotty-milestone-release.md
@@ -63,7 +63,7 @@ For more details also follow the [Migrating the Ecosystem](https://www.scala-lan
 
 Firstly thank you for all the hard work in issue reporting! Being feature complete means that our
 issue tracker will now be more important than ever. We encourage you to stress
-the compiler and report self contained test-cases! Bug minimization is hard and
+the compiler and report self-contained test-cases! Bug minimization is hard and
 an art form! Help us unearth those nasty bugs! ✊
 
 Last but not least we restate the mission of Scala 3. Scala has pioneered the
diff --git a/docs/blog/_posts/2020-04-29-24th-dotty-milestone-release.md b/docs/blog/_posts/2020-04-29-24th-dotty-milestone-release.md
@@ -6,7 +6,7 @@ authorImg: /images/anatolii.png
 date: 2020-04-29
 ---
 
-Hello! We are excited to announce 0.24.0-RC1 of Dotty. In this version, we have updated the standard library to 2.13.2. Also, we have made some work to make error messages more user friendly and a bunch of other polishings to the language.
+Hello! We are excited to announce 0.24.0-RC1 of Dotty. In this version, we have updated the standard library to 2.13.2. Also, we have made some work to make error messages more user-friendly and a bunch of other polishings to the language.
 
 You can try out this version right now, from the comfort of your SBT, by visiting the [home page](https://dotty.epfl.ch/) and scrolling down to the "Create a Dotty Project" section.
 
diff --git a/docs/docs/contributing/procedures/release.md b/docs/docs/contributing/procedures/release.md
@@ -41,7 +41,7 @@ Note that after the first stage of the release cycle (see "Publishing artifacts
 - `<stable-version>` *tag* of the stable version being released
 - `<rc-version>` *tag* of the RC version being released
 
-However you may end up with as many as 6 tasks being run. The auxiliary tasks may include:
+However, you may end up with as many as 6 tasks being run. The auxiliary tasks may include:
 
 - *commit* tests of the *tags* specified above. You may have two of these, corresponding to the two tags. You should see them appearing to have the same commit hash in the CI, but one of them will have the tag next to it and the other one will not. The *tag* one must remain, as the CI tasks on tags publish to maven. CI tasks on commits do not. So it is safe to cancel the task running on the commit, if the commit hash is the same as that of the tag's task commit.
 - Older commit from the `master` branch. Look for all the tasks run on the `master` branch in the CI and see if there are more than one of these. Then, find the one testing the most recent commit of the branch. The others can safely be canceled.
@@ -58,7 +58,7 @@ Above, `<stable_release>` is the stable version being released. For example, if
 
 Copy and paste the output into the release issue.
 
-The ecosystem update section for some projects also mentions a set of criteria upon which the project is to be marked in the checklist. When the Travis build status is specified next to the project's name, it is to be understood that this build must pass after all of the other criteria of that project are checked. Note that due to caching, the label image next to the link may not reflect the real status of the build. Therefore, to verify the status, click on the link and make sure that your recent commit passes.
+The ecosystem update section for some projects also mentions a set of criteria upon which the project is to be marked in the checklist. When the Travis build status is specified next to the project's name, it is to be understood that this build must pass after all the other criteria of that project are checked. Note that due to caching, the label image next to the link may not reflect the real status of the build. Therefore, to verify the status, click on the link and make sure that your recent commit passes.
 
 When no criteria is specified, common sense is to be used.
 
diff --git a/docs/docs/internals/debug-macros.md b/docs/docs/internals/debug-macros.md
@@ -4,7 +4,7 @@ title: "Debug Macros"
 ---
 
 Complex macros may break invariants of the compiler, which leads to compiler crashes.
-Here we lists common compiler crashes and how to deal with them.
+Here we list common compiler crashes and how to deal with them.
 
 ## position not set
 
diff --git a/docs/docs/internals/explicit-nulls.md b/docs/docs/internals/explicit-nulls.md
@@ -82,7 +82,7 @@ Within `Types.scala`, we defined some extractors to work with nullable unions:
 }
 ```
 
-These extractor will call utility methods in `NullOpsDecorator.scala`. All of these
+This extractor will call utility methods in `NullOpsDecorator.scala`. All of these
 are methods of the `Type` class, so call them with `this` as a receiver:
 
 - `stripNull` syntactically strips all `Null` types in the union:
diff --git a/docs/docs/internals/overall-structure.md b/docs/docs/internals/overall-structure.md
@@ -82,7 +82,7 @@ context".
 
 With these two conventions in place, it has turned out that implicit contexts
 work amazingly well as a device for dependency injection and bulk
-parameterization.  There is of course always the danger that an unexpected
+parameterization. There is of course always the danger that an unexpected
 implicit will be passed, but in practice this has not turned out to be much of
 a problem.
 
diff --git a/docs/docs/internals/periods.md b/docs/docs/internals/periods.md
@@ -4,7 +4,7 @@ title: "Dotc's concept of time"
 ---
 
 Conceptually, the `dotc` compiler's job is to maintain views of various
-artifacts associated with source code at all points in time.  But what is
+artifacts associated with source code at all points in time. But what is
 *time* for `dotc`? In fact, it is a combination of compiler runs and compiler
 phases.
 
diff --git a/docs/docs/reference/changed-features/compiler-plugins.md b/docs/docs/reference/changed-features/compiler-plugins.md
@@ -33,7 +33,7 @@ dotc -Xplugin:pluginA.jar -Xplugin:pluginB.jar Test.scala
 
 The compiler will examine the jar provided, and look for a property file named
 `plugin.properties` in the root directory of the jar. The property file specifies
-the fully qualified plugin class name. The format of a property file is as follow:
+the fully qualified plugin class name. The format of a property file is as follows:
 
 ```properties
 pluginClass=dividezero.DivideZero
@@ -99,7 +99,7 @@ the `PluginPhase` trait. In order to specify when the phase is executed, we also
 need to specify a `runsBefore` and `runsAfter` constraints that are list of phase
 names.
 
-We can now transform trees by by overriding methods like `transformXXX`.
+We can now transform trees by overriding methods like `transformXXX`.
 
 ## Writing a Research Compiler Plugin
 
diff --git a/docs/docs/reference/changed-features/interpolation-escapes.md b/docs/docs/reference/changed-features/interpolation-escapes.md
@@ -3,7 +3,7 @@ layout: doc-page
 title: Escapes in interpolations
 ---
 
-In Scala 2 there was no straightforward way to represnt 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 or not the " shold be escaped or used as a terminator.
+In Scala 2 there was 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 Dotty, you can use the `$` meta character of interpolations to escape a `"` character.
 
diff --git a/docs/docs/reference/contextual/derivation.md b/docs/docs/reference/contextual/derivation.md
@@ -391,7 +391,7 @@ This means that code for generic type classes has to ensure that type exploratio
 lockstep and it has to assert this conformance in some places using casts. If generic type classes are correctly
 written these casts will never fail.
 
-As mentioned, however, the compiler-provided mechansim is intentionally very low level and it is anticipated that
+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 Dotty'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
diff --git a/docs/docs/reference/contextual/motivation.md b/docs/docs/reference/contextual/motivation.md
@@ -73,7 +73,7 @@ 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 them.
+ - First, some 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
diff --git a/docs/docs/reference/contextual/relationship-implicits.md b/docs/docs/reference/contextual/relationship-implicits.md
@@ -119,7 +119,7 @@ implicit class CircleDecorator(c: Circle) extends AnyVal {
   def circumference: Double = c.radius * math.Pi * 2
 }
 ```
-Abstract extension methods in traits that are implemented in given instances have no direct counterpart in Scala-2. The only way to simulate these is to make implicit classes available through imports. The Simulacrum macro library can automate this process in some cases.
+Abstract extension methods in traits that are implemented in given instances have no direct counterpart in Scala-2. The only way to simulate this is to make implicit classes available through imports. The Simulacrum macro library can automate this process in some cases.
 
 ### Typeclass Derivation
 
diff --git a/docs/docs/reference/contextual/typeclasses.md b/docs/docs/reference/contextual/typeclasses.md
@@ -154,7 +154,7 @@ Applying the `List.map` ability with the following mapping function as parameter
 
 Now, applying the `List.map` ability with the following mapping function as parameter: `mapping: A => List[B]` would result in a `List[List[B]]`.  
 
-To avoid avoid managing lists of lists, we may want to "flatten" the values in a single list.
+To avoid managing lists of lists, we may want to "flatten" the values in a single list.
 
 That's where `Monad` enters the party. A `Monad` for type `F[?]` is a `Functor[F]` with 2 more abilities: 
 * the flatten ability we just described: turning `F[A]` to `F[B]` when given a `mapping: A => F[B]` function
diff --git a/docs/docs/reference/dropped-features/this-qualifier.md b/docs/docs/reference/dropped-features/this-qualifier.md
@@ -5,7 +5,7 @@ title: Dropped: private[this] and protected[this]
 
 The `private[this]` and `protected[this]` access modifiers are deprecated and will be phased out.
 
-Previously, these modifier were needed
+Previously, these modifiers were needed
 
  - for avoiding the generation of getters and setters
  - for excluding code under a `private[this]` from variance checks. (Scala 2 also excludes `protected[this]` but this was found to be unsound and was therefore removed).
diff --git a/docs/docs/reference/features-classification.md b/docs/docs/reference/features-classification.md
@@ -46,7 +46,7 @@ These constructs replace existing constructs with the aim of making the language
  provide a simple and general way to express aggregation, which can replace the
  previous facade pattern of package objects inheriting from classes.
  - [Vararg patterns](changed-features/vararg-patterns.md) now use the form `: _*` instead of `@ _*`, mirroring vararg expressions,
- - [Creator applications](other-new-features/creator-applications.md) allow to use simple function call syntax
+ - [Creator applications](other-new-features/creator-applications.md) allow using simple function call syntax
  instead of `new` expressions. `new` expressions stay around as a fallback for
  the cases where creator applications cannot be used.
 
diff --git a/docs/docs/reference/metaprogramming/erased-terms-spec.md b/docs/docs/reference/metaprogramming/erased-terms-spec.md
@@ -59,5 +59,5 @@ title: "Erased Terms Spec"
 
 7. Overriding
    * Member definitions overriding each other must both be `erased` or not be `erased`
-   * `def foo(x: T): U` cannot be overridden by `def foo(erased x: T): U` an vice-versa
+   * `def foo(x: T): U` cannot be overridden by `def foo(erased x: T): U` and vice-versa
 
diff --git a/docs/docs/reference/metaprogramming/simple-smp.md b/docs/docs/reference/metaprogramming/simple-smp.md
@@ -142,7 +142,7 @@ To prove (2):
    - `t1` is a simple term but `t2` is not. Then by the second IH. `t2 ==> t22`, hence `t ==> t1 t22`.
 
  - The case `t = ’t2` is not typable.
- - If `t = ~t2` then by inversion we have `E2 ~  |- t2: ’T2`, for some some type `T2`.
+ - If `t = ~t2` then by inversion we have `E2 ~  |- t2: ’T2`, for some type `T2`.
    By the first I.H., we have one of
 
    - `t2 = v`. Since `t2: ’T2`, we must have `v = ’u`, for some simple term `u`, hence `t = ~’u`.
diff --git a/docs/docs/reference/metaprogramming/staging.md b/docs/docs/reference/metaprogramming/staging.md
@@ -7,7 +7,7 @@ The framework expresses at the same time compile-time meta-programming and
 multi-stage programming. We can think of compile-time meta-programming as a
 two stage compilation process: one that we write the code in top-level splices,
 that will be used for code generation (macros) and one that will perform all
-necessecary evaluations at compile-time and an object program that we will run
+necessary evaluations at compile-time and an object program that we will run
 as usual. What if we could synthesize code at run-time and offer one extra stage
 to the programmer? Then we can have a value of type `Expr[T]` at run-time that we
 can essentially treat as a typed-syntax tree that we can either _show_ as a
diff --git a/docs/docs/reference/metaprogramming/toc.md b/docs/docs/reference/metaprogramming/toc.md
diff --git a/docs/docs/reference/new-types/type-lambdas-spec.md b/docs/docs/reference/new-types/type-lambdas-spec.md
diff --git a/docs/docs/reference/new-types/type-lambdas.md b/docs/docs/reference/new-types/type-lambdas.md
diff --git a/docs/docs/reference/other-new-features/creator-applications.md b/docs/docs/reference/other-new-features/creator-applications.md
diff --git a/docs/docs/reference/other-new-features/indentation.md b/docs/docs/reference/other-new-features/indentation.md
diff --git a/docs/docs/reference/overview.md b/docs/docs/reference/overview.md
diff --git a/docs/docs/resources/talks.md b/docs/docs/resources/talks.md
diff --git a/tests/run-custom-args/tasty-interpreter/notes.md b/tests/run-custom-args/tasty-interpreter/notes.md
