Merge pull request #11169 from dotty-staging/update-enum-docs-deprecation

Document deprecation of enum cases

Author: bishabosha

docs/docs/reference/enums/enums.md

@@ -88,6 +88,48 @@ object Planet:
 end Planet
 ```
 
+### Deprecation of Enum Cases
+
+As a library author, you may want to signal that an enum case is no longer intended for use. However you could still want to gracefully handle the removal of a case from your public API, such as special casing deprecated cases.
+
+To illustrate, say that the `Planet` enum originally had an additional case:
+```diff
+ enum Planet(mass: Double, radius: Double):
+    ...
+    case Neptune extends Planet(1.024e+26, 2.4746e7)
++   case Pluto   extends Planet(1.309e+22, 1.1883e3)
+ end Planet
+```
+
+We now want to deprecate the `Pluto` case. First we add the `scala.deprecated` annotation to `Pluto`:
+
+```diff
+ enum Planet(mass: Double, radius: Double):
+    ...
+    case Neptune extends Planet(1.024e+26, 2.4746e7)
+-   case Pluto   extends Planet(1.309e+22, 1.1883e3)
++
++   @deprecated("refer to IAU definition of planet")
++   case Pluto extends Planet(1.309e+22, 1.1883e3)
+ end Planet
+```
+
+Outside the lexical scopes of `enum Planet` or `object Planet`, references to `Planet.Pluto` will produce a deprecation warning, but within those scopes we can still reference it to implement introspection over the deprecated cases:
+
+```scala
+trait Deprecations[T <: reflect.Enum] {
+   extension (t: T) def isDeprecatedCase: Boolean
+}
+
+object Planet {
+   given Deprecations[Planet] with {
+      extension (p: Planet)
+         def isDeprecatedCase = p == Pluto
+   }
+}
+```
+We could imagine that a library may use [type class derivation](../contextual/derivation.md) to automatically provide an instance for `Deprecations`.
+
 ### Compatibility with Java Enums
 If you want to use the Scala-defined enums as [Java enums](https://docs.oracle.com/javase/tutorial/java/javaOO/enum.html), you can do so by extending
 the class `java.lang.Enum`, which is imported by default, as follows: