Update documentation of union types

 - Introduce hard and soft unions
 - Explain how transparency of base traits influences type inference
 - Drop outdated note on possible future changes

Author: odersky

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

@@ -72,6 +72,10 @@ a non-union type, for this purpose we define the _join_ of a union type `T1 |
 `T1`,...,`Tn`. Note that union types might still appear as type arguments in the
 resulting type, this guarantees that the join is always finite.
 
+The _visible join_ of a union type is its join where all operands of the intersection that
+are instances of [transparent](../other-new-features/transparent-traits.md) traits or classes are removed.
+
+
 ### Example
 
 Given
@@ -80,31 +84,50 @@ Given
 trait C[+T]
 trait D
 trait E
-class A extends C[A] with D
-class B extends C[B] with D with E
+transparent trait X
+class A extends C[A], D, X
+class B extends C[B], D, E, X
 ```
 
-The join of `A | B` is `C[A | B] & D`
+The join of `A | B` is `C[A | B] & D & X` and the visible join of `A | B` is `C[A | B] & D`.
+
+## Hard and Soft Union Types
+
+We distinguish between hard and soft union types. A _hard_ union type is a union type that's explicitly
+written in the source. For instance, in
+```scala
+val x: Int | String = ...
+```
+`Int | String` would be a hard union type. A _soft_ union type is a type that arises from type checking
+an alternative of expressions. For instance, the type of the expression
+```scala
+val x = 1
+val y = "abc"
+if cond then x else y
+```
+is the soft unon type `Int | String`. Similarly for match expressions. The type of
+```scala
+x match
+  case 1 => x
+  case 2 => "abc"
+  case 3 => List(1, 2, 3)
+```
+is the soft union type `Int | "abc" | List[Int]`.
+
 
 ## Type inference
 
 When inferring the result type of a definition (`val`, `var`, or `def`) and the
-type we are about to infer is a union type, then we replace it by its join.
+type we are about to infer is a soft union type, then we replace it by its visible join,
+provided it is not empty.
 Similarly, when instantiating a type argument, if the corresponding type
 parameter is not upper-bounded by a union type and the type we are about to
-instantiate is a union type, we replace it by its join. This mirrors the
+instantiate is a soft union type, we replace it by its visible join, provided it is not empty.
+This mirrors the
 treatment of singleton types which are also widened to their underlying type
 unless explicitly specified. The motivation is the same: inferring types
 which are "too precise" can lead to unintuitive typechecking issues later on.
 
-**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 [PR #2330](https://github.com/lampepfl/dotty/pull/2330) and
-[Issue #4867](https://github.com/lampepfl/dotty/issues/4867) for further discussions.
-
 ### Example
 
 ```scala

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

@@ -8,8 +8,9 @@ A union type `A | B` has as values all values of type `A` and also all values of
 
 
 ```scala
-case class UserName(name: String)
-case class Password(hash: Hash)
+trait ID
+case class UserName(name: String) extends ID
+case class Password(hash: Hash) extends ID
 
 def help(id: UserName | Password) =
   val user = id match
@@ -22,7 +23,10 @@ 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](https://docs.scala-lang.org/overviews/repl/overview.html) transcript:
+type is explicitly given or the common supertype of all alternatives is [transparent](../other-new-features/transparent-traits.md).
+
+
+This can be seen in the following [REPL](https://docs.scala-lang.org/overviews/repl/overview.html) transcript:
 
 ```scala
 scala> val password = Password(123)
@@ -32,15 +36,36 @@ scala> val name = UserName("Eve")
 val name: UserName = UserName(Eve)
 
 scala> if true then name else password
-val res2: Object = UserName(Eve)
+val res1: ID = UserName(Eve)
 
 scala> val either: Password | UserName = if true then name else password
-val either: Password | UserName = UserName(Eve)
+val either: UserName | Password = UserName(Eve)
 ```
-
-The type of `res2` is `Object & Product`, which is a supertype of
-`UserName` and `Password`, but not the least supertype `Password |
-UserName`.  If we want the least supertype, we have to give it
+The type of `res1` is `ID`, which is a supertype of
+`UserName` and `Password`, but not the least supertype `UserName | Password`.
+If we want the least supertype, we have to give it
 explicitly, as is done for the type of `either`.
 
+The inference behavior changes if the common supertrait `ID` is declared `transparent`:
+```scala
+transparent trait ID
+```
+In that case the union type is not widened.
+```scala
+scala> if true then name else password
+val res2: UserName | Password = UserName(Eve)
+```
+The more precise union type is also inferred if `UserName` and `Password` are declared without an explicit
+parent, since in that case their implied superclass is `Object`, which is among the classes that are
+assumed to be transparent. See [Transparent Traits and Classes](../other-new-features/transparent-traits.md)
+for a list of such classes.
+```scala
+case class UserName(name: String)
+case class Password(hash: Hash)
+
+scala> if true then UserName("Eve") else Password(123)
+val res3: UserName | Password = UserName(Eve)
+```
+
+
 [More details](./union-types-spec.md)

tests/pos/transparent-union.scala

@@ -0,0 +1,8 @@
+transparent trait ID
+case class UserName(name: String) extends ID
+case class Password(hash: Int) extends ID
+
+val password: Password = Password(123)
+val name = UserName("Eve")
+val res = if ??? then name else password
+val _: UserName | Password = res