check position of typeparam and document example

Author: bishabosha

compiler/src/dotty/tools/dotc/typer/VarianceChecker.scala

@@ -168,8 +168,14 @@ class VarianceChecker(using Context) {
       case Some(VarianceError(tvar, required)) =>
         def msg =
           val enumAddendum =
-            if sym.owner.isAllOf(EnumCase) && sym.owner.isClass then
-              i"\nenum case ${sym.owner} may require explicit type parameters to resolve this issue"
+            val towner = tvar.owner
+            if towner.isAllOf(EnumCase) && towner.isClass
+              && tvar.span.exists && towner.span.exists
+              && tvar.span.start < towner.span.start // implies that `tvar` was not user declared
+            then
+              val example =
+                "See an example at http://dotty.epfl.ch/docs/reference/enums/adts.html#parameter-variance-of-enums"
+              i"\nenum case ${towner} requires explicit declaration of $tvar to resolve this issue.\n$example"
             else
               ""
           i"${varianceLabel(tvar.flags)} $tvar occurs in ${varianceLabel(required)} position in type ${sym.info} of $sym$enumAddendum"

docs/docs/reference/enums/adts.md

@@ -78,6 +78,43 @@ object Option {
 }
 ```
 
+### Parameter Variance of Enums
+
+By default, parameterized cases of enums with type parameters will copy the type parameters of their parent, along
+with any variance notations. As usual, it is important to use type parameters carefully when they are variant, as shown
+below:
+
+The following `View` enum has a contravariant type parameter `T` and a single case `Refl`, representing a function
+mapping a type `T` to itself:
+```scala
+enum View[-T]:
+  case Refl(f: T => T)
+```
+The definition of `Refl` is incorrect, as it uses contravariant type `T` in the covariant result position of a
+function type, leading to the following error:
+```scala
+-- Error: View.scala:2:12 --------
+2 |  case Refl(f: T => T)
+  |            ^^^^^^^^^
+  |contravariant type T occurs in covariant position in type T => T of value f
+  |enum case class Refl requires explicit declaration of type T to resolve this issue.
+```
+Because `Refl` does not declare explicit parameters, it looks to the compiler like the following:
+```scala
+enum View[-T]:
+  case Refl[/*synthetic*/-T1](f: T1 => T1) extends View[T1]
+```
+
+The compiler has inferred for `Refl` the contravariant type parameter `T1`, following `T` in `View`.
+We can now clearly see that `Refl` needs to declare its own type parameters to satisfy the variance condition,
+and can remedy the error by the following change to `Refl`:
+
+```diff
+enum View[-T]:
+-  case Refl(f: T => T)
++  case Refl[T](f: T => T) extends View[T]
+```
+
 Enumerations and ADTs have been presented as two different
 concepts. But since they share the same syntactic construct, they can
 be seen simply as two ends of a spectrum and it is perfectly possible

tests/neg-custom-args/fatal-warnings/enum-variance.check

@@ -1,5 +1,10 @@
 -- Error: tests/neg-custom-args/fatal-warnings/enum-variance.scala:2:12 ------------------------------------------------
-2 |  case Refl(f: T => T) // error: covariant T in contravariant position... enum case may require explicit type parameters
+2 |  case Refl(f: T => T) // error: enum case class Refl requires explicit declaration of type T
   |            ^^^^^^^^^
-  |            covariant type T occurs in contravariant position in type T => T of value f
-  |            enum case class Refl may require explicit type parameters to resolve this issue
+  |            contravariant type T occurs in covariant position in type T => T of value f
+  |            enum case class Refl requires explicit declaration of type T to resolve this issue.
+  |            See an example at http://dotty.epfl.ch/docs/reference/enums/adts.html#parameter-variance-of-enums
+-- Error: tests/neg-custom-args/fatal-warnings/enum-variance.scala:5:16 ------------------------------------------------
+5 |  case Refl[-T](f: T => T) extends ExplicitView[T] // error: contravariant type T occurs in covariant position
+  |                ^^^^^^^^^
+  |                contravariant type T occurs in covariant position in type T => T of value f

tests/neg-custom-args/fatal-warnings/enum-variance.scala

@@ -1,2 +1,11 @@
-enum View[+T]:
-  case Refl(f: T => T) // error: covariant T in contravariant position... enum case may require explicit type parameters
+enum View[-T]:
+  case Refl(f: T => T) // error: enum case class Refl requires explicit declaration of type T
+
+enum ExplicitView[-T]: // desugared version of View
+  case Refl[-T](f: T => T) extends ExplicitView[T] // error: contravariant type T occurs in covariant position
+
+enum InvariantView[-T, +U] extends (T => U):
+  case Refl[T](f: T => T) extends InvariantView[T, T]
+
+  final def apply(t: T): U = this match
+    case refl: Refl[t] => refl.f(t)