Merge pull request #7833 from dvirf1/documentation-changes

minor fixes to the documentation

Author: smarter

docs/docs/reference/contextual/given-clauses.md

@@ -18,9 +18,9 @@ def max[T](x: T, y: T)(given ord: Ord[T]): T =
 Here, `ord` is an _implicit parameter_ introduced with a `given` clause.
 The `max` method can be applied as follows:
 ```scala
-max(2, 3)(given IntOrd)
+max(2, 3)(given intOrd)
 ```
-The `(given IntOrd)` part passes `IntOrd` as an argument for the `ord` parameter. But the point of
+The `(given intOrd)` part passes `intOrd` as an argument for the `ord` parameter. But the point of
 implicit parameters is that this argument can also be left out (and it usually is). So the following
 applications are equally valid:
 ```scala
@@ -60,8 +60,8 @@ With this setup, the following calls are all well-formed, and they all normalize
 ```scala
 minimum(xs)
 maximum(xs)(given descending)
-maximum(xs)(given descending(given ListOrd))
-maximum(xs)(given descending(given ListOrd(given IntOrd)))
+maximum(xs)(given descending(given listOrd))
+maximum(xs)(given descending(given listOrd(given intOrd)))
 ```
 
 ## Multiple Given Clauses
@@ -92,9 +92,9 @@ But `f(global)(given sym, kind)` would give a type error.
 The method `summon` in `Predef` returns the given instance of a specific type. For example,
 the given instance for `Ord[List[Int]]` is produced by
 ```scala
-summon[Ord[List[Int]]]  // reduces to ListOrd given IntOrd
+summon[Ord[List[Int]]]  // reduces to listOrd given intOrd
 ```
-The `summon` method is simply defined as the (non-widening) identity function over a implicit parameter.
+The `summon` method is simply defined as the (non-widening) identity function over an implicit parameter.
 ```scala
 def summon[T](given x: T): x.type = x
 ```

docs/docs/reference/contextual/multiversal-equality.md

@@ -171,7 +171,7 @@ does not work, since it refers to the covariant parameter `T` in a nonvariant co
 ```scala
   def contains[U >: T](x: U): Boolean
 ```
-This generic version of `contains` is the one used in the current (Scala 2.12) version of `List`.
+This generic version of `contains` is the one used in the current (Scala 2.13) version of `List`.
 It looks different but it admits exactly the same applications as the `contains(x: Any)` definition we started with.
 However, we can make it more useful (i.e. restrictive) by adding an `Eql` parameter:
 ```scala

docs/docs/reference/contextual/relationship-implicits.md

@@ -86,10 +86,10 @@ Explicit arguments to parameters of given clauses _must_ be written using `given
 mirroring the definition syntax. E.g, `max(2, 3)(given 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 `the` method corresponds to `implicitly` in Scala 2.
+The `summon` method corresponds to `implicitly` in Scala 2.
 It is precisely the same as the `the` method in Shapeless.
-The difference between `the` (in both versions) and `implicitly` is
-that `the` can return a more precise type than the type that was
+The difference between `summon` (or `the`) and `implicitly` is
+that `summon` can return a more precise type than the type that was
 asked for.
 
 ### Context Bounds
@@ -108,7 +108,7 @@ def (c: Circle) circumference: Double = c.radius * math.Pi * 2
 ```
 could be simulated to some degree by
 ```scala
-implicit class CircleDeco(c: Circle) extends AnyVal {
+implicit class CircleDecorator(c: Circle) extends AnyVal {
   def circumference: Double = c.radius * math.Pi * 2
 }
 ```
@@ -162,12 +162,12 @@ given Position = pos
 
 An abstract implicit `val` or `def` in Scala 2 can be expressed in Dotty using a regular abstract definition and an alias given. E.g., Scala 2's
 ```scala
-implicit def symDeco: SymDeco
+implicit def symDecorator: SymDecorator
 ```
 can be expressed in Dotty as
 ```scala
-def symDeco: SymDeco
-given SymDeco = symDeco
+def symDecorator: SymDecorator
+given SymDecorator = symDecorator
 ```
 
 ## Implementation Status and Timeline

docs/docs/reference/new-types/dependent-function-types.md

@@ -17,7 +17,7 @@ val extractor: (e: Entry) => e.Key = extractKey  // a dependent function value
 ```
 Scala already has _dependent methods_, i.e. methods where the result
 type refers to some of the parameters of the method. Method
-`extractKey` is an example. Its result type, `e.key` refers its
+`extractKey` is an example. Its result type, `e.Key` refers its
 parameter `e` (we also say, `e.Key` _depends_ on `e`). But so far it
 was not possible to turn such methods into function values, so that
 they can be passed as parameters to other functions, or returned as
@@ -30,8 +30,8 @@ In Dotty this is now possible. The type of the `extractor` value above is
 (e: Entry) => e.Key
 ```
 
-This type describes function values that take any argument `x` of type
-`Entry` and return a result of type `x.Key`.
+This type describes function values that take any argument `e` of type
+`Entry` and return a result of type `e.Key`.
 
 Recall that a normal function type `A => B` is represented as an
 instance of the `Function1` trait (i.e. `Function1[A, B]`) and

docs/docs/reference/new-types/union-types-spec.md

@@ -38,14 +38,14 @@ case _: (A | B) => ...
   A & (B | C) =:= A & B | A & C
   ```
 
-From these rules it follows that the _least upper bound_ (lub) of a set of type
+From these rules it follows that the _least upper bound_ (lub) of a set of types
 is the union of these types. This replaces the
 [definition of least upper bound in the Scala 2 specification](https://www.scala-lang.org/files/archive/spec/2.12/03-types.html#least-upper-bounds-and-greatest-lower-bounds).
 
 ## Motivation
 
 The primary reason for introducing union types in Scala is that they allow us to
-guarantee that for every set of type, we can always form a finite lub. This is
+guarantee that for every set of types, we can always form a finite lub. This is
 both useful in practice (infinite lubs in Scala 2 were approximated in an ad-hoc
 way, resulting in imprecise and sometimes incredibly long types) and in theory
 (the type system of Scala 3 is based on the

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

@@ -93,7 +93,7 @@ Export clauses can appear in classes or they can appear at the top-level. An exp
 
 It is a standard recommendation to prefer composition over inheritance. This is really an application of the principle of least power: Composition treats components as blackboxes whereas inheritance can affect the internal workings of components through overriding. Sometimes the close coupling implied by inheritance is the best solution for a problem, but where this is not necessary the looser coupling of composition is better.
 
-So far, object oriented languages including Scala made it much easer to use inheritance than composition. Inheritance only requires an `extends` clause whereas composition required a verbose elaboration of a sequence of forwarders. So in that sense, OO languages are pushing
+So far, object oriented languages including Scala made it much easier to use inheritance than composition. Inheritance only requires an `extends` clause whereas composition required a verbose elaboration of a sequence of forwarders. So in that sense, OO languages are pushing
 programmers to a solution that is often too powerful. Export clauses redress the balance. They make composition relationships as concise and easy to express as inheritance relationships. Export clauses also offer more flexibility than extends clauses since members can be renamed or omitted.
 
 Export clauses also fill a gap opened by the shift from package objects to toplevel definitions. One occasionally useful idiom that gets lost in this shift is a package object inheriting from some class. The idiom is often used in a facade like pattern, to make members