improve doc about enum types (digital-asset#2168)

* add a more meat to doc about enum types * Update docs/source/app-dev/daml-lf-translation.rst Co-Authored-By: Stefano Baghino <43749967+stefanobaghino-da@users.noreply.github.com>
iggy-da · Jul 16, 2019 · 3a93647 · 3a93647
1 parent 1a93db2
commit 3a93647
Show file tree

Hide file tree

Showing 2 changed files with 30 additions and 8 deletions.
diff --git a/docs/source/app-dev/daml-lf-translation.rst b/docs/source/app-dev/daml-lf-translation.rst
@@ -58,12 +58,13 @@ For example: the DAML pair type ``(Int, Text)`` is translated to ``daml-prim:DA.
 Data types
 **********
 
-DAML-LF has two kinds of data declarations:
+DAML-LF has three kinds of data declarations:
 
 - **Record** types, which define a collection of data
 - **Variant** or **sum** types, which define a number of alternatives
+- **Enum**, which defines simplified **sum** types without type parameters nor argument.
 
-:ref:`Data type declarations in DAML <daml-ref-data-constructors>` (starting with the ``data`` keyword) are translated to either record or variant types. It’s sometimes not obvious what they will be translated to, so this section lists many examples of data types in DAML and their translations in DAML-LF.
+:ref:`Data type declarations in DAML <daml-ref-data-constructors>` (starting with the ``data`` keyword) are translated to record, variant or enum types. It’s sometimes not obvious what they will be translated to, so this section lists many examples of data types in DAML and their translations in DAML-LF.
 
 .. In the tables below, the left column uses DAML 1.2 syntax and the right column uses the notation from the `DAML-LF specification <https://github.com/digital-asset/daml/blob/master/daml-lf/spec/daml-lf-1.rst>`_.
 
@@ -102,10 +103,14 @@ Variant declarations
      - DAML-LF translation
    * - ``data Foo = Bar Int | Baz Text``
      - ``variant Foo ↦ Bar Int64 | Baz Text``
-   * - ``data Foo = Bar Int | Baz ()``
-     - ``variant Foo ↦ Bar Int64 | Baz Unit``
-   * - ``data Foo = Bar Int | Baz``
-     - ``variant Foo ↦ Bar Int64 | Baz Unit``
+   * - ``data Foo a = Bar a | Baz Text``
+     - ``variant Foo a ↦ Bar a | Baz Text``
+   * - ``data Foo = Bar Unit | Baz Text``
+     - ``variant Foo ↦ Bar Unit | Baz Text``
+   * - ``data Foo = Bar Unit | Baz``
+     - ``variant Foo ↦ Bar Unit | Baz Unit``
+   * - ``data Foo a = Bar | Baz``
+     - ``variant Foo a ↦ Bar Unit | Baz Unit``
    * - ``data Foo = Foo Int``
      - ``variant Foo ↦ Foo Int64``
    * - ``data Foo = Bar Int``
@@ -123,6 +128,20 @@ Variant declarations
    * - ``data Foo = Bar { bar1: Int; bar2: Decimal } | Baz { baz1: Text; baz2: Date }``
      - ``data Foo ↦ Bar Foo.Bar | Baz Foo.Baz``, ``record Foo.Bar ↦ { bar1: Int64; bar2: Decimal }``, ``record Foo.Baz ↦ { baz1: Text; baz2: Date }``
 
+Enum declarations
+=================
+
+.. list-table::
+   :widths: 10 15
+   :header-rows: 1
+
+   * - DAML declaration
+     - DAML-LF declaration
+   * - ``data Foo = Bar | Baz``
+     - ``enum Foo ↦ Bar | Baz``
+   * - ``data Color = Red | Green | Blue``
+     - ``enum Color ↦ Red | Green | Blue``
+
 Banned declarations
 ===================
 

diff --git a/unreleased.rst b/unreleased.rst
@@ -61,8 +61,11 @@ HEAD — ongoing
 
   + Add support for DAML-LF intern package IDs.
 
-- [Ledger API] Add support for ``enum`` types. Simple ``variant`` types will
-  be replaced by ``enum`` types when using a DAML-LF ``1.6`` archive.
+- [Ledger API] Add support for ``enum`` types. Simple DAML ``variant`` types
+  will be mapped to DAML-LF ``enum`` types when using a DAML-LF ``1.6``
+  archive. Ledger API Value Protobuf provides the new ``Enum`` message.
+  This message must be used to communicate this new data type throught the
+  API.
 
 - [Java Codegen]: Add support for ``enum`` types. ``enum`` types are mapped to
   standard java enum. See `Generate Java code from DAML