Documentation fixes for enums

anatoliykmetyuk · anatoliykmetyuk · commit 7e6869d6a4d2 · 2019-06-06T15:54:31.000+02:00
diff --git a/compiler/src/dotty/tools/dotc/ast/DesugarEnums.scala b/compiler/src/dotty/tools/dotc/ast/DesugarEnums.scala
@@ -122,8 +122,8 @@ object DesugarEnums {
 
   /** A creation method for a value of enum type `E`, which is defined as follows:
    *
-   *   private def $new($tag: Int, $name: String) = new E {
-   *     def ordinal = $tag
+   *   private def $new(_$ordinal: Int, $name: String) = new E {
+   *     def $ordinal = $tag
    *     override def toString = $name
    *     $values.register(this)
    *   }
diff --git a/docs/docs/reference/enums/desugarEnums.md b/docs/docs/reference/enums/desugarEnums.md
@@ -120,11 +120,11 @@ map into case classes or vals.
 
    expands to a value definition in `E`'s companion object:
 
-       val C = new <parents> { <body>; def enumTag = n; $values.register(this) }
+       val C = new <parents> { <body>; def ordinal = n; $values.register(this) }
 
    where `n` is the ordinal number of the case in the companion object,
    starting from 0.  The statement `$values.register(this)` registers the value
-   as one of the `enumValues` of the enumeration (see below). `$values` is a
+   as one of the `values` of the enumeration (see below). `$values` is a
    compiler-defined private value in the companion object.
 
    It is an error if a value case refers to a type parameter of the enclosing `enum`
@@ -140,10 +140,10 @@ map into case classes or vals.
 
    However, unlike for a regular case class, the return type of the associated
    `apply` method is a fully parameterized type instance of the enum class `E`
-   itself instead of `C`.  Also the enum case defines an `enumTag` method of
+   itself instead of `C`.  Also the enum case defines an `ordinal` method of
    the form
 
-       def enumTag = n
+       def ordinal = n
 
    where `n` is the ordinal number of the case in the companion object,
    starting from 0.
@@ -159,12 +159,9 @@ Non-generic enums `E` that define one or more singleton cases
 are called _enumerations_. Companion objects of enumerations define
 the following additional members.
 
-   - A method `enumValue` of type `scala.collection.immutable.Map[Int, E]`.
-     `enumValue(n)` returns the singleton case value with ordinal number `n`.
-   - A method `enumValueNamed` of type `scala.collection.immutable.Map[String, E]`.
-     `enumValueNamed(s)` returns the singleton case value whose `toString`
-     representation is `s`.
-   - A method `enumValues` which returns an `Iterable[E]` of all singleton case
+   - A method `valueOf(name: String): E`. It returns the singleton case value whose
+     `toString` representation is `name`.
+   - A method `values` which returns an `Array[E]` of all singleton case
      values in `E`, in the order of their definitions.
 
 Companion objects of enumerations that contain at least one simple case define in addition:
@@ -173,12 +170,14 @@ Companion objects of enumerations that contain at least one simple case define i
      ordinal number and name. This method can be thought as being defined as
      follows.
 
-         def $new(tag: Int, name: String): ET = new E {
-           def enumTag = tag
-           def toString = name
-           $values.register(this)   // register enum value so that `valueOf` and `values` can return it.
+         private def $new(\_$ordinal: Int, $name: String) = new E {
+           def $ordinal = $tag
+           override def toString = $name
+           $values.register(this) // register enum value so that `valueOf` and `values` can return it.
          }
 
+The `$ordinal` method above is used to generate the `ordinal` method if the enum does not extend a `java.lang.Enum` (as Scala enums do not extend `java.lang.Enum`s unless explicitly specified). In case it does, there is no need to generate `ordinal` as `java.lang.Enum` defines it.
+
 ### Scopes for Enum Cases
 
 A case in an `enum` is treated similarly to a secondary constructor. It can access neither the enclosing `enum` using `this`, nor its value parameters or instance members using simple
diff --git a/docs/docs/reference/enums/enums.md b/docs/docs/reference/enums/enums.md
@@ -33,27 +33,25 @@ explicit extends clause.
 ### Methods defined for enums
 
 The values of an enum correspond to unique integers. The integer
-associated with an enum value is returned by its `enumTag` method:
+associated with an enum value is returned by its `ordinal` method:
 
 ```scala
 scala> val red = Color.Red
 val red: Color = Red
-scala> red.enumTag
+scala> red.ordinal
 val res0: Int = 0
 ```
 
-The companion object of an enum also defines three utility methods.
-The `enumValue` and `enumValueNamed` methods obtain an enum value
-by its tag or its name. The `enumValues` method returns all enum values
-defined in an enumeration in an `Iterable`.
+The companion object of an enum also defines two utility methods.
+The `valueOf` method obtains an enum value
+by its name. The `values` method returns all enum values
+defined in an enumeration in an `Array`.
 
 ```scala
-scala> Color.enumValue(1)
-val res1: Color = Green
-scala> Color.enumValueNamed("Blue")
-val res2: Color = Blue
-scala> Color.enumValues
-val res3: collection.Iterable[Color] = MapLike(Red, Green, Blue)
+scala> Color.valueOf("Blue")
+val res0: Color = Blue
+scala> Color.values
+val res1: Array[Color] = Array(Red, Green, Blue)
 ```
 
 ### User-defined members of enums
@@ -84,16 +82,32 @@ object Planet {
   def main(args: Array[String]) = {
     val earthWeight = args(0).toDouble
     val mass = earthWeight / Earth.surfaceGravity
-    for (p <- enumValues)
+    for (p <- values)
       println(s"Your weight on $p is ${p.surfaceWeight(mass)}")
   }
 }
 ```
 
+### Compatibility with Java Enums
+If you want to use the Scala-defined enums as Java enums, you can do so by extending `compat.JEnum` class as follows:
+
+```scala
+enum Color extends compat.JEnum[Color] { case Red, Green, Blue }
+```
+
+The type parameter comes from the Java enum [definition](https://docs.oracle.com/javase/8/docs/api/index.html?java/lang/Enum.html) and should me the same as the type of the enum. The compiler will transform the definition above so that `Color` extends `java.lang.Enum`.
+
+After defining `Color` like that, you can use like you would a Java enum:
+
+```scala
+scala> Color.Red.compareTo(Color.Green)
+val res15: Int = -1
+```
+
 ### Implementation
 
 Enums are represented as `sealed` classes that extend the `scala.Enum` trait.
-This trait defines a single method, `enumTag`:
+This trait defines a single public method, `ordinal`:
 
 ```scala
 package scala
@@ -102,7 +116,7 @@ package scala
 trait Enum {
 
   /** A number uniquely identifying a case of an enum */
-  def enumTag: Int
+  def ordinal: Int
 }
 ```
 
@@ -112,7 +126,7 @@ For instance, the `Venus` value above would be defined like this:
 ```scala
 val Venus: Planet =
   new Planet(4.869E24, 6051800.0) {
-    def enumTag: Int = 1
+    def ordinal: Int = 1
     override def toString: String = "Venus"
     // internal code to register value
   }
