Merge pull request #10 from tegonal/doc-opaque-type-alias

doc(opaque type alias): revise text, remove workaround

Author: robstoll

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

@@ -12,7 +12,8 @@ object Logarithms {
 
   object Logarithm {
 
-    // These are the ways to lift to the logarithm type
+    // These are the two ways to lift to the Logarithm type
+
     def apply(d: Double): Logarithm = math.log(d)
 
     def safe(d: Double): Option[Logarithm] =
@@ -28,19 +29,22 @@ object Logarithms {
 }
 ```
 
-This introduces `Logarithm` as a new type, which is implemented as `Double` but is different from it. The fact that `Logarithm` is the same as `Double` is only known in the scope where
-`Logarithm` is defined which in this case is object `Logarithms`.
-
-The public API of `Logarithm` consists of the `apply` and `safe` methods that convert from doubles to `Logarithm` values, an extension method `toDouble` that converts the other way,
-and operations `+` and `*` on logarithm values. The implementations of these functions
-type-check because within object `Logarithms`, the type `Logarithm` is just an alias of `Double`.
+This introduces `Logarithm` as a new abstract type, which is implemented as `Double`. 
+The fact that `Logarithm` is the same as `Double` is only known in the scope where
+`Logarithm` is defined which in the above example corresponds to the object `Logarithms`.
+Or in other words, within the scope it is treated as type alias, but this is opaque to the outside world 
+where in consequence `Logarithm` is treated as own type and has nothing to do with `Double`.
 
-Outside its scope, `Logarithm` is treated as a new abstract type. So the
-following operations would be valid because they use functionality implemented in the `Logarithm` object.
+The public API of `Logarithm` consists of the `apply` and `safe` methods defined in the companion object. 
+They convert from `Double`s to `Logarithm` values. Moreover, a collective extension `logarithmOps` provides the extension methods `toDouble` that converts the other way,
+and operations `+` and `*` on `Logarithm` values. 
+As a reminder, the implementations of these functions
+type-check because within the object `Logarithms`, the type `Logarithm` is just a type alias of `Double`.
+Outside of its scope, `Logarithm` is treated as a new abstract type. So the
+following operations would be valid because they use functionality implemented in the `Logarithms` object.
 
 ```scala
-import Logarithms._
-import Predef.{any2stringadd => _, _}
+import Logarithms.Logarithm
 
 val l = Logarithm(1.0)
 val l2 = Logarithm(2.0)
@@ -54,11 +58,9 @@ But the following operations would lead to type errors:
 val d: Double = l       // error: found: Logarithm, required: Double
 val l2: Logarithm = 1.0 // error: found: Double, required: Logarithm
 l * 2                   // error: found: Int(2), required: Logarithm
-l / l2                  // error: `/` is not a member fo Logarithm
+l / l2                  // error: `/` is not a member of Logarithm
 ```
 
-Aside: the `any2stringadd => _` import suppression is necessary since otherwise the universal `+` operation in `Predef` would take precedence over the `+` extension method in `logarithmOps`. We plan to resolve this wart by eliminating `any2stringadd`.
-
 ### Bounds For Opaque Type Aliases
 
 Opaque type aliases can also come with bounds. Example:
@@ -81,7 +83,7 @@ object Access {
   val ReadOrWrite: PermissionChoice = Read | Write
 }
 ```
-The `Access` object defines three opaque types:
+The `Access` object defines three opaque type aliases:
 
  - `Permission`, representing a single permission,
  - `Permissions`, representing a set of permissions with the meaning "all of these permissions granted",
@@ -98,7 +100,7 @@ Because of that, the `|` extension method in `Access` does not cause infinite re
 Also, the definition of `ReadWrite` must use `|`,
 even though an equivalent definition outside `Access` would use `&`.
 
-All three opaque types have the same underlying representation type `Int`. The
+All three opaque type aliases have the same underlying representation type `Int`. The
 `Permission` type has an upper bound `Permissions & PermissionChoice`. This makes
 it known outside the `Access` object that `Permission` is a subtype of the other
 two types.  Hence, the following usage scenario type-checks.