Update docs

Author: odersky

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

@@ -88,7 +88,7 @@ treatment of singleton types which are also widened to their underlying type
 unless explicitly specified. and the motivation is the same: inferring types
 which are "too precise" can lead to unintuitive typechecking issues later on.
 
-Note: Since this behavior severely limits the usability of union types, it might
+Note: Since this behavior limits the usability of union types, it might
 be changed in the future. For example by not widening unions that have been
 explicitly written down by the user and not inferred, or by not widening a type
 argument when the corresponding type parameter is covariant. See
@@ -149,7 +149,3 @@ the erased lub is computed as follows:
   The reason to pick last is that we prefer classes over traits that way,
   which leads to more predictable bytecode and (?) faster dynamic dispatch.
 
-## Limitations
-
-In a union type `A | B`, neither `A` nor `B` is allowed to be a singleton type.
-This is an implementation restriction that may be lifted in the future.

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

@@ -3,7 +3,8 @@ layout: doc-page
 title: "Union Types"
 ---
 
-Used on types, the `|` operator creates a union type.
+A union type `A | B` has as values all values of type `A` and also all values of type `B`.
+
 
 ```scala
 case class UserName(name: String) {
@@ -22,13 +23,11 @@ def help(id: UserName | Password) = {
 }
 ```
 
-Union types are dual of intersection types. Values of type `A | B` are
-all values of type `A` and all values of type `B`. `|` is _commutative_:
+Union types are duals of intersection types. `|` is _commutative_:
 `A | B` is the same type as `B | A`.
 
 The compiler will assign a union type to an expression only if such a
-type is explicitly given.
-This can be seen in the following REPL transcript:
+type is explicitly given. This can be seen in the following REPL transcript:
 
 ```scala
 scala> val password = Password(123)