Add explanation for @superTrait annotation to docs

Author: odersky

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

@@ -300,7 +300,7 @@ trait ConstraintHandling[AbstractContext] {
    *      (i.e. `inst.widenSingletons <:< bound` succeeds with satisfiable constraint)
    *   2. If `inst` is a union type, approximate the union type from above by an intersection
    *      of all common base types, provided the result is a subtype of `bound`.
-   *   3. If `inst` an intersection such that some operands are super trait instances
+   *   3. If `inst` is an intersection such that some operands are super trait instances
    *      and others are not, replace as many super trait instances as possible with Any
    *      as long as the result is still a subtype of `bound`. But fall back to the
    *      original type if the resulting widened type is a supertype of all dropped

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

@@ -1310,6 +1310,8 @@ class Definitions {
 
   @tu lazy val assumedSuperTraits =
     Set(ComparableClass, ProductClass, SerializableClass,
+      // add these for now, until we had a chance to retrofit 2.13 stdlib
+      // we should do a more through sweep through it then.
       ctx.requiredClass("scala.collection.SortedOps"),
       ctx.requiredClass("scala.collection.StrictOptimizedSortedSetOps"),
       ctx.requiredClass("scala.collection.generic.DefaultSerializable"),

docs/docs/reference/other-new-features/super-traits.md

@@ -43,13 +43,24 @@ are treated automatically as super traits. Other traits can be turned into super
 Every trait can be declared as a super trait. Typically super traits are traits that influence the implementation of inheriting classes and traits and that are not usually used as types by themselves. Two examples from the
 standard collection library:
 
- - `IterableLike`, which provides method implementations for an `Iterable`
- - `IndexedSeqOptimized`, which optimises some of these implementations for
+ - `IterableOps`, which provides method implementations for an `Iterable`
+ - `StrictOptimizedSeqOps`, which optimises some of these implementations for
    sequences with efficient indexing.
 
 Generally, any trait that is extended recursively is a good candidate to be
 declared a super trait.
 
+### Retro-Fitting Scala 2 Libraries
+
+To allow cross-building between Scala 2 and 3, super traits can also be
+introduced by adding the `@superTrait` annotation, which is defined in package `scala.annotation`. Example:
+```scala
+import scala.annotation.superTrait
+
+@superTrait trait StrictOptimizedSeqOps[+A, +CC[_], +C] ...
+```
+The `@superTrait` annotation will be deprecated and removed in some later version of Scala when cross-building with Scala 2 will no longer be a concern.
+
 ### Rules for Inference
 
 Super 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 super traits are dropped from intersections where possible.