Add enum example in documentation and a test for 'case class cannot extend enum'

compiler/test/dotty/tools/dotc/reporting/ErrorMessagesTests.scala

@@ -19,6 +19,20 @@ class ErrorMessagesTests extends ErrorMessagesTest {
     checkMessagesAfter(FrontEnd.name)("""class Foo""")
     .expectNoErrors
 
+  @Test def caseClassExtendsEnum =
+    checkMessagesAfter(RefChecks.name) {
+      """
+        |enum Foo {}
+        |case class Bar() extends Foo
+      """.stripMargin
+    }
+      .expect { (ictx, messages) ⇒
+        implicit val ctx: Context = ictx
+        assertMessageCount(1, messages)
+        val errorMsg = messages.head
+        assertEquals("normal case class Bar in package <empty> cannot extend an enum", errorMsg.msg)
+      }
+
   @Test def typeMismatch =
     checkMessagesAfter(FrontEnd.name) {
       """

docs/docs/reference/enums/enums.md

@@ -88,6 +88,35 @@ object Planet {
       println(s"Your weight on $p is ${p.surfaceWeight(mass)}")
   }
 }
+```
+### A specific use case of enum
+
+Two enums can be combined into a different type as shown below:
+
+```scala
+
+trait Animal
+object Animal {
+  def enumValues: Iterable[Animal] = Dog.enumValues ++ Cat.enumValues
+  def enumValueNamed = Dog.enumValueNamed ++ Cat.enumValueNamed
+}
+
+enum Dog extends Animal {
+  case GermanShepherd, Labrador, Boxer
+}
+
+enum Cat extends Animal {
+  case PersianCat, Ragdoll, ScottishFold
+}
+
+object Main {
+  def main(args: Array[String]): Unit = {
+    val values: Iterable[Animal] = Animal.enumValues
+    val boxer_dog: Animal = Animal.enumValueNamed("Boxer")
+    val ragdoll_cat: Animal = Animal.enumValueNamed("Ragdoll")
+  }
+}
+
 ```
 
 ### Implementation

tests/pending/neg/i5008

@@ -0,0 +1,2 @@
+enum Foo {}
+enum Bar extends Foo {} // error