Merge pull request #9034 from asakaev/docs

Improve documentation

Author: liufengyun

.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: ''

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 }

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.
 

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,

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

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:

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:

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

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.
 

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.

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
 

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:

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
 

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.
 

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

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

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).

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.
 

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
 

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`.

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

docs/docs/reference/metaprogramming/toc.md

@@ -33,7 +33,7 @@ introduce the following fundamental facilities:
 
 4. [TASTy Reflection](./tasty-reflect.md) Quotations are a "black-box"
    representation of code. They can be parameterized and composed using
-   splices but their structure cannot be analyzed from the outside. Tasty
+   splices, but their structure cannot be analyzed from the outside. Tasty
    reflection gives a way to analyze code structure by partly revealing the representation type of a piece of code in a standard API. The representation
    type is a form of typed abstract syntax tree, which gives rise to the `TASTy`
    moniker.

docs/docs/reference/new-types/type-lambdas-spec.md

@@ -102,7 +102,7 @@ type O2[X] = List[X]
 ```
 would be treated as covariant, `X` is used covariantly on its right-hand side.
 
-**Note**: The decision to treat `Nothing` as universal bottom type is provisional, and might be changed afer further discussion.
+**Note**: The decision to treat `Nothing` as universal bottom type is provisional, and might be changed after further discussion.
 
 **Note**: Scala 2 and 3 differ in that Scala 2 also treats `Any` as universal top-type. This is not done in Scala 3. See also the discussion on [kind polymorphism](../other-new-features/kind-polymorphism.md)
 

docs/docs/reference/new-types/type-lambdas.md

@@ -11,6 +11,6 @@ a type definition.
 ```
 
 For instance, the type above defines a binary type constructor, which maps arguments `X` and `Y` to `Map[Y, X]`.
-Type parameters of type lambdas can have bounds but they cannot carry `+` or `-` variance annotations.
+Type parameters of type lambdas can have bounds, but they cannot carry `+` or `-` variance annotations.
 
 [More details](./type-lambdas-spec.md)

docs/docs/reference/other-new-features/creator-applications.md

@@ -3,7 +3,7 @@ layout: doc-page
 title: "Creator Applications"
 ---
 
-Creator applications allow to use simple function call syntax to create instances
+Creator applications allow using simple function call syntax to create instances
 of a class, even if there is no apply method implemented. Example:
 ```scala
 class StringBuilder(s: String) {

docs/docs/reference/other-new-features/indentation.md

@@ -342,7 +342,7 @@ Significant indentation is enabled by default. It can be turned off by giving an
 
 The Dotty compiler can rewrite source code to indented code and back.
 When invoked with options `-rewrite -indent` it will rewrite braces to
-indented regions where possible. When invoked with with options `-rewrite -noindent` it will rewrite in the reverse direction, inserting braces for indentation regions.
+indented regions where possible. When invoked with options `-rewrite -noindent` it will rewrite in the reverse direction, inserting braces for indentation regions.
 The `-indent` option only works on [new-style syntax](./control-syntax.html). So to go from old-style syntax to new-style indented code one has to invoke the compiler twice, first with options `-rewrite -new-syntax`, then again with options
 `-rewrite -indent`. To go in the opposite direction, from indented code to old-style syntax, it's `-rewrite -noindent`, followed by `-rewrite -old-syntax`.
 

docs/docs/reference/overview.md

@@ -42,7 +42,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.
 

tests/run-custom-args/tasty-interpreter/notes.md

@@ -4,7 +4,7 @@
 - Abstract platform operations
   - Arrays
 - Proxies
-  - Enviroment of the object
+  - Environment of the object
   - `this` in Env
   - Class with fields
   - Class with custom constructor (and secondary)