Update interface ref docs to clarify that {pre,post}consuming qualifi…

…ers are not supported (#13523) changelog_begin changelog_end
digital-asset · Apr 7, 2022 · 4ca8abf · 4ca8abf
1 parent d51ea74
commit 4ca8abf
Show file tree

Hide file tree

Showing 2 changed files with 14 additions and 7 deletions.
diff --git a/docs/source/daml/code-snippets-dev/Interfaces.daml b/docs/source/daml/code-snippets-dev/Interfaces.daml
@@ -19,7 +19,7 @@ interface MyInterface where
   ensure myGuard (method1 this)
 -- INTERFACE_ENSURE_END
 
--- INTERFACE_CHOICE_BEGIN
+-- INTERFACE_CHOICES_BEGIN
   choice MyChoice : (ContractId MyInterface, Int)
     with
       argument1 : Bool
@@ -29,7 +29,12 @@ interface MyInterface where
       let n0 = method2 this
       let n1 = method3 this argument1 argument2 n0
       pure (self, n1)
--- INTERFACE_CHOICE_END
+
+  nonconsuming choice MyNonConsumingChoice : Int
+    controller method1 this
+    do
+      pure $ method2 this
+-- INTERFACE_CHOICES_END
 
 -- INTERFACE_METHODS_TOP_LEVEL_BEGIN
 func1 : Implements t MyInterface => t -> Party

diff --git a/docs/source/daml/reference/interfaces.rst b/docs/source/daml/reference/interfaces.rst
@@ -78,17 +78,19 @@ Interface choices
 
 .. literalinclude:: ../code-snippets-dev/Interfaces.daml
    :language: daml
-   :start-after: -- INTERFACE_CHOICE_BEGIN
-   :end-before: -- INTERFACE_CHOICE_END
+   :start-after: -- INTERFACE_CHOICES_BEGIN
+   :end-before: -- INTERFACE_CHOICES_END
 
 - Interface choices work in a very similar way to template choices. Any contract
   of an implementing interface will grant the choice to the controlling party.
 - Interface methods can be used to define the controller of a choice
   (e.g. ``method1``) as well as the actions that run when the choice is
   *exercised* (e.g. ``method2`` and ``method3``).
-- As for template choices, the ``choice`` keyword can be prefixed with one of
-  ``preconsuming``, ``postconsuming`` or ``nonconsuming`` to further specify
-  the behaviour of the choice when exercised.
+- As for template choices, the ``choice`` keyword can be optionally prefixed
+  with the ``nonconsuming`` keyword to specify that the contract will not be
+  consumed when the choice is exercised. If not specified, the choice will be
+  ``consuming``. Note that the ``preconsuming`` and ``postconsuming`` qualifiers
+  are not supported on interface choices.
 - See :doc:`choices` for full reference information, but note that
   controller-first syntax is not supported for interface choices.