Update docs

Author: odersky

docs/docs/reference/contextual/query-types.md

@@ -118,15 +118,10 @@ As a larger example, here is a way to define constructs for checking arbitrary p
 object PostConditions {
   opaque type WrappedResult[T] = T
 
-  private object WrappedResult {
-    def wrap[T](x: T): WrappedResult[T] = x
-    def unwrap[T](x: WrappedResult[T]): T = x
-  }
-
-  def result[T] given (r: WrappedResult[T]): T = WrappedResult.unwrap(r)
+  def result[T] given (r: WrappedResult[T]): T = f
 
   def (x: T) ensuring [T](condition: given WrappedResult[T] => Boolean): T = {
-    implied for WrappedResult[T] = WrappedResult.wrap(x)
+    implied for WrappedResult[T] = x
     assert(condition)
     x
   }

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

@@ -0,0 +1,63 @@
+---
+layout: doc-page
+title: "Opaque Type Aliases: More Details"
+---
+
+### Syntax
+
+```
+Modifier          ::=  ...
+                    |  ‘opaque’
+```
+`opaque` is a [soft modifier](../soft-modifier.html). It can still be used as a normal identifier when it is not in front of a definition keyword.
+
+Opaque type aliases must be members of classes, traits, or objects, or they are defined
+at the top-level. They cannot be defined in local blocks.
+
+### Type Checking
+
+The general form of a (monomorphic) opaque type alias is
+```scala
+opaque type T >: L <: U = R
+```
+where the lower bound `L` and the upper bound `U` may be missing, in which case they are assumed to be `scala.Nothing` and `scala.Any`, respectively. If bounds are given, it is checked that the right hand side `R` conforms to them, i.e. `L <: R` and `R <: U`.
+
+Inside the scope of the alias definition, the alias is transparent: `T` is treated
+as a normal alias of `R`. Outside its scope, the alias is treated as the abstract type
+```scala
+type T >: L <: U`
+```
+A special case arises if the opaque type is defined in an object. Example:
+```
+object o {
+  opaque type T = R
+}
+```
+In this case we have inside the object (also for non-opaque types) that `o.T` is equal to
+`T` or its expanded form `o.this.T`. Equality is understood here as mutual subtyping, i.e.
+`o.T <: o.this.T` and `o.this.T <: T`. Furthermore, we have by the rules of opaque types
+that `o.this.T` equals `R`. The two equalities compose. That is, inside `o`, it is
+also known that `o.T` is equal to `R`. This means the following code type-checks:
+```scala
+object o {
+  opaque type T = Int
+  val x: Int = id(2)
+}
+def id(x: o.T): o.T = x
+```
+
+### Relationship to SIP 35
+
+Opaque types in Dotty are an evolution from what is described in
+[Scala SIP 35](https://docs.scala-lang.org/sips/opaque-types.html).
+
+The differences compared to the state described in this SIP are:
+
+ 1. Opaque type aliases cannot be defined anymore in local statement sequences.
+ 2. The scope where an opaque type alias is visible is now the whole scope where
+    it is defined, instead of just a companion object.
+ 3. The notion of a companion object for opaque type aliases has been dropped.
+ 4. Opaque type aliases can have bounds.
+ 5. The notion of type equality involving opaque type aliases has been clarified. It was
+    strengthened with respect to the previous implementation of SIP 35.
+

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

@@ -6,39 +6,42 @@ title: "Opaque Type Aliases"
 Opaque types aliases provide type abstraction without any overhead. Example:
 
 ```scala
-opaque type Logarithm = Double
-```
-
-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 companion object of `Logarithm`. Here is a possible companion object:
+object Logarithms {
 
-```scala
-object Logarithm {
+  opaque type Logarithm = Double
 
-  // These are the ways to lift to the logarithm type
-  def apply(d: Double): Logarithm = math.log(d)
+  object Logarithm {
 
-  def safe(d: Double): Option[Logarithm] =
-    if (d > 0.0) Some(math.log(d)) else None
+    // These are the ways to lift to the logarithm type
+    def apply(d: Double): Logarithm = math.log(d)
 
-  // This is the first way to unlift the logarithm type
-  def exponent(l: Logarithm): Double = l
+    def safe(d: Double): Option[Logarithm] =
+      if (d > 0.0) Some(math.log(d)) else None
+  }
 
   // Extension methods define opaque types' public APIs
-  implicit class LogarithmOps(val `this`: Logarithm) extends AnyVal {
-    // This is the second way to unlift the logarithm type
-    def toDouble: Double = math.exp(`this`)
-    def +(that: Logarithm): Logarithm = Logarithm(math.exp(`this`) + math.exp(that))
-    def *(that: Logarithm): Logarithm = Logarithm(`this` + that)
+  implied LogarithmOps {
+    def (x: Logarithm) toDouble: Double = math.exp(x)
+    def (x: Logarithm) + (y: Logarithm): Logarithm = Logarithm(math.exp(x) + math.exp(y))
+    def (x: Logarithm) * (y: Logarithm): Logarithm = Logarithm(x + y)
   }
 }
 ```
 
-The companion object contains with the `apply` and `safe` methods ways to convert from doubles to `Logarithm` values. It also adds an `exponent` function and a decorator that implements `+` and `*` on logarithm values, as well as a conversion `toDouble`. All this is possible because within object `Logarithm`, the type `Logarithm` is just an alias of `Double`.
+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`.
 
-Outside the companion object, `Logarithm` is treated as a new abstract type. So the
+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.
 
 ```scala
+  import Logarithms._
+  import Predef.{any2stringadd => _, _}
+
   val l = Logarithm(1.0)
   val l2 = Logarithm(2.0)
   val l3 = l * l2
@@ -54,6 +57,53 @@ But the following operations would lead to type errors:
   l / l2                  // error: `/` is not a member fo Logarithm
 ```
 
-`opaque` is a [soft modifier](../soft-modifier.html).
+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:
+```scala
+object Access {
+
+  opaque type Permissions = Int
+  opaque type PermissionChoice = Int
+  opaque type Permission <: Permissions & PermissionChoice = Int
+
+  def (x: Permissions) & (y: Permissions): Permissions = x & y
+  def (x: PermissionChoice) | (y: PermissionChoice): PermissionChoice = x | y
+  def (x: Permissions) is (y: Permissions) = (x & y) == y
+  def (x: Permissions) isOneOf (y: PermissionChoice) = (x & y) != 0
+
+  val NoPermission: Permission = 0
+  val ReadOnly: Permission = 1
+  val WriteOnly: Permission = 2
+  val ReadWrite: Permissions = ReadOnly & WriteOnly
+  val ReadOrWrite: PermissionChoice = ReadOnly | WriteOnly
+}
+```
+The `Access` object defines three opaque types:
+
+ - `Permission`, representing a single permission,
+ - `Permissions`, representing a conjunction (logical "and") of permissions,
+ - `PermissionChoice`, representing a disjunction (logical "or") of permissions.
+
+All three opaque types 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.
+```scala
+object User {
+  import Access._
+
+  case class Item(rights: Permissions)
+
+  val x = Item(ReadOnly)  // OK, since Permission <: Permissions
+
+  assert( x.rights.is(ReadWrite) == false )
+  assert( x.rights.isOneOf(ReadOrWrite) == true )
+}
+```
+On the other hand, the call `x.rights.isOneOf(ReadWrite)` would give a type error
+since `Permissions` and `PermissionChoice` are different, unrelated types outside `Access`.
 
-For more details, see [Scala SIP 35](https://docs.scala-lang.org/sips/opaque-types.html).
+[More details](opaques-details.md)

tests/pos/postconditions.scala

@@ -1,15 +1,10 @@
 object PostConditions {
   opaque type WrappedResult[T] = T
 
-  private object WrappedResult {
-    def wrap[T](x: T): WrappedResult[T] = x
-    def unwrap[T](x: WrappedResult[T]): T = x
-  }
-
-  def result[T] given (r: WrappedResult[T]): T = WrappedResult.unwrap(r)
+  def result[T] given (r: WrappedResult[T]): T = r
 
   def (x: T) ensuring [T](condition: given WrappedResult[T] => Boolean): T = {
-    implied for WrappedResult[T] = WrappedResult.wrap(x)
+    implied for WrappedResult[T] = x
     assert(condition)
     x
   }

tests/pos/reference/opaque.scala

@@ -19,7 +19,7 @@ object Logarithms {
   }
 }
 
-object Test {
+object LogTest {
   import Logarithms._
   import Predef.{any2stringadd => _, _}