Document consumability qualifiers in the reference docs (digital-asse…

…t#4134) * Document consumability qualifiers and their privacy implications in the reference docs CHANGELOG_BEGIN [Documentation] Documented consumability qualifiers in the DAML reference docs, along with their privacy implications CHANGELOG_END * Fix WARNING: Title underline too short. * Fix DAML compile errors on reference docs code * Addresses digital-asset#4134 (comment) * Addresses digital-asset#4134 (comment) * Addresses digital-asset#4134 (comment) * Addresses digital-asset#4134 (comment) * Addresses digital-asset#4134 (comment) * Review and fix according to improvements part of digital-asset#4164 * Addresses digital-asset#4134 (comment) * Grammar fix * Address digital-asset#4134 (comment) * Address digital-asset#4134 (comment) * Address digital-asset#4134 (review)
axman6 · Jan 24, 2020 · b87ff49 · b87ff49
1 parent 0be3e72
commit b87ff49
Show file tree

Hide file tree

Showing 3 changed files with 82 additions and 9 deletions.
diff --git a/docs/source/daml/code-snippets/Reference.daml b/docs/source/daml/code-snippets/Reference.daml
@@ -78,6 +78,22 @@ template NameOfTemplate
 -- end choice-first controller snippet
         do
           return () -- replace () with the actual return type
+-- start choice-first preconsuming snippet
+    preconsuming choice ExampleChoice5
+          : () -- replace () with the actual return type
+-- end choice-first preconsuming snippet
+        with -- params
+        controller exampleParty
+          do
+            return ()
+-- start choice-first postconsuming snippet
+    postconsuming choice ExampleChoice6
+          : () -- replace () with the actual return type
+-- end choice-first postconsuming snippet
+        with -- params
+        controller exampleParty
+          do
+            return ()
 -- start choice-first nonconsuming snippet
     nonconsuming choice ExampleChoice3
           : () -- replace () with the actual return type
@@ -100,6 +116,18 @@ template NameOfTemplate
 -- end controller-first params snippet
         do
           return () -- replace () with the actual return type
+-- start controller-first preconsuming snippet
+      preconsuming ExampleChoice7
+          : () -- replace () with the actual return type
+-- end controller-first preconsuming snippet
+        do
+          return () -- replace () with the actual return type
+-- start controller-first postconsuming snippet
+      postconsuming ExampleChoice8
+          : () -- replace () with the actual return type
+-- end controller-first postconsuming snippet
+        do
+          return () -- replace () with the actual return type
 -- start controller-first nonconsuming snippet
       nonconsuming ExampleChoice4
           : () -- replace () with the actual return type

diff --git a/docs/source/daml/reference/choices.rst b/docs/source/daml/reference/choices.rst
@@ -72,10 +72,57 @@ Controllers
 
   The conjunction of **all** the parties are required to authorize when this choice is exercised.
 
-.. _daml-ref-anytime:
+.. _daml-ref-consumability:
+
+Contract consumption
+====================
+
+If no qualifier is present, choices are *consuming*: the contract is archived before the evaluation of the choice body and both the controllers and all contract stakeholders see all consequences of the action.
+
+Preconsuming choices
+********************
+
+.. literalinclude:: ../code-snippets/Reference.daml
+   :language: daml
+   :start-after: -- start choice-first preconsuming snippet
+   :end-before: -- end choice-first preconsuming snippet
+   :caption: Option 1 for specifying choices: choice name first
+
+.. literalinclude:: ../code-snippets/Reference.daml
+   :language: daml
+   :start-after: -- start controller-first preconsuming snippet
+   :end-before: -- end controller-first preconsuming snippet
+   :caption: Option 2 for specifying choices: controller first
+
+- ``preconsuming`` keyword. Optional.
+- Makes a choice pre-consuming: the contract is archived before the body of the exercise is executed.
+- The archival behavior is analogous to the *consuming* default behavior.
+- Unlike what happens the in *consuming* behavior, though, only the controllers and signatories of the contract see all consequences of the action. If the choice archives the contract, other stakeholders merely see an archive action.
+- Can be thought as a non-consuming choice that implicitly archives the contract before anything else happens
+
+Postconsuming choices
+*********************
+
+.. literalinclude:: ../code-snippets/Reference.daml
+   :language: daml
+   :start-after: -- start choice-first postconsuming snippet
+   :end-before: -- end choice-first postconsuming snippet
+   :caption: Option 1 for specifying choices: choice name first
+
+.. literalinclude:: ../code-snippets/Reference.daml
+   :language: daml
+   :start-after: -- start controller-first postconsuming snippet
+   :end-before: -- end controller-first postconsuming snippet
+   :caption: Option 2 for specifying choices: controller first
+
+- ``postconsuming`` keyword. Optional.
+- Makes a choice post-consuming: the contract is archived after the body of the exercise is executed.
+- The contract can still be used in the body of the exercise.
+- Only the controllers and signatories of the contract see all consequences of the action. If the choice archives the contract, other stakeholders merely see an archive action.
+- Can be thought as a non-consuming choice that implicitly archives the contract after the choice has been exercised
 
 Non-consuming choices
-=====================
+*********************
 
 .. literalinclude:: ../code-snippets/Reference.daml
    :language: daml
@@ -91,9 +138,8 @@ Non-consuming choices
 
 - ``nonconsuming`` keyword. Optional.
 - Makes a choice non-consuming: that is, exercising the choice does not archive the contract.
-
-  By default, choices are *consuming*: when a choice on a contract is exercised, that contract instance is *archived*. Archived means that it's permanently marked as being inactive, and no more choices can be exercised on it, though it still exists on the ledger.
-- This is useful in the many situations when you want to be able to exercise a choice more than once.
+- Only the controllers and signatories of the contract see all consequences of the action. If the choice archives the contract, other stakeholders merely see an archive action.
+- Useful in the many situations when you want to be able to exercise a choice more than once.
 
 .. _daml-ref-return-type:
 

diff --git a/docs/source/daml/reference/structure.rst b/docs/source/daml/reference/structure.rst
@@ -90,10 +90,9 @@ Here's the structure of a choice inside a template. There are two ways of specif
 
     Who can exercise the choice.
 
-:ref:`consumability <daml-ref-anytime>`
-    ``nonconsuming`` keyword
-
-    By default, contracts are archived when a choice on them is exercised, which means that choices can no longer be exercised on them. If you include ``nonconsuming``, this choice can be exercised over and over.
+:ref:`consumption annotation <daml-ref-consumability>`
+    Optionally one of ``preconsuming``, ``postconsuming``, ``nonconsuming``, which changes the behavior of the choice with respect to privacy and if and when the contract is archived.
+    See :ref:`contract consumption in choices <daml-ref-consumability>` for more details.
 
 :ref:`a name <daml-ref-choice-name>`
     Must begin with a capital letter. Must be unique - choices in different templates can't have the same name.