Restrict re-resolution of equality to opaque types

Also, document what is done in the doc page for opaque types.

Author: odersky

compiler/src/dotty/tools/dotc/transform/ElimOpaque.scala

@@ -22,6 +22,7 @@ object ElimOpaque {
 
 /** Rewrites opaque type aliases to normal alias types */
 class ElimOpaque extends MiniPhase with DenotTransformer {
+  thisPhase =>
   import ast.tpd._
 
   override def phaseName: String = ElimOpaque.name
@@ -58,13 +59,14 @@ class ElimOpaque extends MiniPhase with DenotTransformer {
   }
 
   /** Resolve overloading of `==` and `!=` methods with the representation
-   *  types in order to avoid boxing. TODO: This should be in the SLS.
+   *  types in order to avoid boxing.
    */
   override def transformApply(tree: Apply)(using Context): Tree =
     val sym = tree.symbol
     if sym == defn.Any_== || sym == defn.Any_!= then
       tree match
-        case Apply(Select(receiver, name: TermName), args) =>
+        case Apply(Select(receiver, name: TermName), args)
+        if atPhase(thisPhase)(receiver.tpe.widen.typeSymbol.isOpaqueAlias) =>
           applyOverloaded(receiver, name, args, Nil, defn.BooleanType)
         case _ =>
           tree

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

@@ -46,6 +46,21 @@ object o {
 def id(x: o.T): o.T = x
 ```
 
+### Translation of Equality
+
+Comparing two values of opaque type with `==` or `!=` normally uses universal equality,
+unless another overloaded `==` or `!=` operator is defined for the type. To avoid
+boxing, the operation is mapped after type checking to the (in-)equality operator
+defined on the underlying type. For instance,
+```scala
+  opaque type T = Int
+
+  ...
+  val x: T
+  val y: T
+  x == y    // uses Int equality for the comparison.
+```
+
 ### Toplevel Opaque Types
 
 An opaque type alias on the toplevel is transparent in all other toplevel definitions in the sourcefile where it appears, but is opaque in nested