Update doc page

Author: odersky

compiler/src/dotty/tools/dotc/core/Definitions.scala

@@ -1763,8 +1763,11 @@ class Definitions {
 
   @tu lazy val assumedTransparentClasses =
     Set[Symbol](ComparableClass, ProductClass, SerializableClass,
+      AnyClass, AnyValClass, ObjectClass, MatchableClass,
       // add these for now, until we had a chance to retrofit 2.13 stdlib
       // we should do a more through sweep through it then.
+      requiredClass("scala.collection.IterableOps"),
+      requiredClass("scala.collection.SeqOps"),
       requiredClass("scala.collection.SortedOps"),
       requiredClass("scala.collection.StrictOptimizedSortedSetOps"),
       requiredClass("scala.collection.generic.DefaultSerializable"),
@@ -1774,10 +1777,6 @@ class Definitions {
       requiredClass("scala.collection.generic.IsSeq"),
       requiredClass("scala.collection.generic.Subtractable"),
       requiredClass("scala.collection.immutable.StrictOptimizedSeqOps"),
-      AnyClass,
-      AnyValClass,
-      ObjectClass,
-      MatchableClass
     )
 
   // ----- primitive value class machinery ------------------------------------------

docs/_docs/reference/other-new-features/transparent-traits.md

@@ -1,6 +1,6 @@
 ---
 layout: doc-page
-title: "Transparent Traits"
+title: "Transparent Traits and Classes"
 nightlyOf: https://docs.scala-lang.org/scala3/reference/other-new-features/transparent-traits.html
 ---
 
@@ -20,12 +20,13 @@ val x = Set(if condition then Val else Var)
 
 Here, the inferred type of `x` is `Set[Kind & Product & Serializable]` whereas one would have hoped it to be `Set[Kind]`. The reasoning for this particular type to be inferred is as follows:
 
-- The type of the conditional above is the [union type](../new-types/union-types.md) `Val | Var`.
-- A union type is widened in type inference to the least supertype that is not a union type.
-  In the example, this type is `Kind & Product & Serializable` since all three traits are traits of both `Val` and `Var`.
+- The type of the conditional above is the [union type](../new-types/union-types.md) `Val | Var`. This union type is treated as "soft", which means it was not explicitly written in the source program, but came from forming an upper bound of the types of
+some alternatives.
+- A soft union type is widened in type inference to the least product of class or trait types that is a supertype of the union type.
+  In the example, this type is `Kind & Product & Serializable` since all three traits are super-traits of both `Val` and `Var`.
   So that type becomes the inferred element type of the set.
 
-Scala 3 allows one to mark a mixin trait as `transparent`, which means that it can be suppressed in type inference. Here's an example that follows the lines of the code above, but now with a new transparent trait `S` instead of `Product`:
+Scala 3 allows one to mark a trait or class as `transparent`, which means that it can be suppressed in type inference. Here's an example that follows the lines of the code above, but now with a new transparent trait `S` instead of `Product`:
 
 ```scala
 transparent trait S
@@ -38,13 +39,40 @@ val x = Set(if condition then Val else Var)
 Now `x` has inferred type `Set[Kind]`. The common transparent trait `S` does not
 appear in the inferred type.
 
-## Transparent Traits
+In the previous example, one could also declare `Kind` as `transparent`:
+```scala
+transparent trait Kind
+```
+The widened union type of `if condition then Val else Var` would then
+_only_ contain the transparent traits `Kind` and `S`. In this case,
+the widening is not performed at all, so `x` would have type `Set[Val | Var]`.
+
+The root classes and traits `Any`, `AnyVal`, `Object`, and `Matchable` are
+considered to be transparent. This means that an expression such
+as
+```scala
+if condition then 1 else "hello"
+```
+will have type `Int | String` instead of the widened type `Any`.
+
 
-The traits [`scala.Product`](https://scala-lang.org/api/3.x/scala/Product.html), [`java.io.Serializable`](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/io/Serializable.html) and [`java.lang.Comparable`](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Comparable.html)
-are treated automatically as transparent. Other traits are turned into transparent traits using the modifier `transparent`. Scala 2 traits can also be made transparent
-by adding a [`@transparentTrait`](https://scala-lang.org/api/3.x/scala/annotation/transparentTrait.html) annotation. This annotation is defined in [`scala.annotation`](https://scala-lang.org/api/3.x/scala/annotation.html). It will be deprecated and phased out once Scala 2/3 interoperability is no longer needed.
 
-Typically, transparent traits are traits
+## Which Traits and Classes Are Transparent?
+
+Traits and classes are declared transparent by adding the modifier `transparent`. Scala 2 traits and classes can also be declared transparent by adding a [`@transparentTrait`](https://scala-lang.org/api/3.x/scala/annotation/transparentTrait.html) annotation. This annotation is defined in [`scala.annotation`](https://scala-lang.org/api/3.x/scala/annotation.html). It will be deprecated and phased out once Scala 2/3 interoperability is no longer needed.
+
+The following classes and traits are automatically treated as transparent:
+```scala
+    scala.Any
+    scala.AnyVal
+    scala.Matchable
+    scala.Product
+    java.lang.Object
+    java.lang.Comparable
+    java.io.Serializable
+```
+
+Typically, transparent types other than the root classes are traits
 that influence the implementation of inheriting classes and traits that are not usually used as types by themselves. Two examples from the standard collection library are:
 
 - [`IterableOps`](https://scala-lang.org/api/3.x/scala/collection/IterableOps.html), which provides method implementations for an [`Iterable`](https://scala-lang.org/api/3.x/scala/collection/Iterable.html).
@@ -55,7 +83,10 @@ declared transparent.
 
 ## Rules for Inference
 
-Transparent traits can be given as explicit types as usual. But they are often elided when types are inferred. Roughly, the rules for type inference say that transparent traits are dropped from intersections where possible.
+Transparent traits and classes can be given as explicit types as usual. But they are often elided when types are inferred. Roughly, the rules for type inference imply the following.
+
+ - Transparent traits and classes are dropped from intersections where possible.
+ - Union types are not widened if widening would result in only transparent supertypes.
 
 The precise rules are as follows:
 
@@ -65,6 +96,6 @@ The precise rules are as follows:
 - If the type inferred so far is of the form `T1 & ... & Tn` where
   `n >= 1`, replace the maximal number of transparent `Ti`s  by `Any`, while ensuring that
   the resulting type is still a subtype of the bound `B`.
-- However, do not perform this widening if all transparent traits `Ti` can get replaced in that way.
+- However, do not perform this widening if all transparent types `Ti` can get replaced in that way. This clause ensures that a single transparent trait instance such as [`Product`](https://scala-lang.org/api/3.x/scala/Product.html) is not widened to [`Any`](https://scala-lang.org/api/3.x/scala/Any.html). Transparent trait instances are only dropped when they appear in conjunction with some other type.
 
-The last clause ensures that a single transparent trait instance such as [`Product`](https://scala-lang.org/api/3.x/scala/Product.html) is not widened to [`Any`](https://scala-lang.org/api/3.x/scala/Any.html). Transparent trait instances are only dropped when they appear in conjunction with some other type.
+- If the original type was a is union type that got widened in a previous step to a product consisting only of transparent types, keep the original union type instead of its widened form.