Update docs to reflect 'controller ... can' syntax deprecation

Also fixed some literalinclude snippets to use blocks instead of line numbers part of #11317
digital-asset · Nov 19, 2021 · 1be9abb · 1be9abb
1 parent 9cdd759
commit 1be9abb
Show file tree

Hide file tree

Showing 42 changed files with 290 additions and 83 deletions.
diff --git a/compiler/daml-extension/syntaxes/TestGrammar.daml b/compiler/daml-extension/syntaxes/TestGrammar.daml
@@ -30,13 +30,13 @@ template FeatureSuggestion
         assert $ elem sponsor founders  -- assert -> source.daml
         create FeatureAssignment with employee, description, sponsor -- create -> source.daml
 
-    -- deprecated syntax
+    -- deprecated syntax: 'controller ... can' will be removed in a future version of Daml.
     controller employee can
       nonconsuming DoNothing : ()
         do
           return ()
 
-    -- deprecated syntax
+    -- deprecated syntax: 'controller ... can' will be removed in a future version of Daml.
     controller employee can
       Revoke : ()
         do pure ()
diff --git a/compiler/damlc/tests/daml-test-files/ChoiceSyntaxes.daml b/compiler/damlc/tests/daml-test-files/ChoiceSyntaxes.daml
@@ -23,7 +23,8 @@ template T with
       do
         pure ()
 
-    -- deprecated syntax
+    -- deprecated syntax: 'controller ... can' will be removed in a future version of Daml.
+    -- This file tests the various options for defining choices, so we keep it until it is removed.
     controller p can
       C3 : () with
           x : ()

diff --git a/compiler/damlc/tests/daml-test-files/SemanticsEvalOrder.daml b/compiler/damlc/tests/daml-test-files/SemanticsEvalOrder.daml
@@ -424,7 +424,9 @@ template T_ControllerCanAddsObserver
     p : Party
   where
     signatory p
-    -- deprecated syntax
+    -- deprecated syntax: 'controller ... can' will be removed in a future version of Daml.
+    -- This tests that `controller X can` implicitly adds `X` as an observer, so we keep
+    -- it until it is removed.
     controller (error @Party "controllerCanAddsObserver OK") can
       C_ControllerCanAddsObserver: ()
         do pure ()

diff --git a/docs/source/app-dev/bindings-java/quickstart.rst b/docs/source/app-dev/bindings-java/quickstart.rst
@@ -273,23 +273,26 @@ Take a look at the Daml that specifies the contract model in the quickstart appl
 #. Open :doc:`Daml Studio </daml/daml-studio>`, a Daml IDE based on VS Code, by running ``daml studio`` from the root of your project.
 #. Using the explorer on the left, open ``daml/Iou.daml``.
 
-The first two lines specify language version and module name:
+The first line specifies the module name:
 
 .. literalinclude:: quickstart/template-root/daml/Iou.daml
   :language: daml
-  :lines: 4-5
+  :start-after: -- BEGIN_IOU_MODULE_NAME
+  :end-before: -- END_IOU_MODULE_NAME
 
 Next, a template called `Iou` is declared together with its datatype. This template has five fields:
 
 .. literalinclude:: quickstart/template-root/daml/Iou.daml
   :language: daml
-  :lines: 9-15
+  :start-after: -- BEGIN_IOU_TEMPLATE_DATATYPE
+  :end-before: -- END_IOU_TEMPLATE_DATATYPE
 
 Conditions for the creation of a contract are specified using the `ensure` and `signatory` keywords:
 
 .. literalinclude:: quickstart/template-root/daml/Iou.daml
   :language: daml
-  :lines: 17-19
+  :start-after: -- BEGIN_IOU_TEMPLATE_CONDITIONS
+  :end-before: -- END_IOU_TEMPLATE_CONDITIONS
 
 In this case, there are two conditions:
 
@@ -304,15 +307,32 @@ Observers are specified using the ``observer`` keyword:
 
 .. literalinclude:: quickstart/template-root/daml/Iou.daml
   :language: daml
-  :lines: 21
+  :start-after: -- BEGIN_IOU_TEMPLATE_OBSERVERS
+  :end-before: -- END_IOU_TEMPLATE_OBSERVERS
 
-Next, *rights* or *choices* are given to ``owner``:
+Next, the *rights* or *choices* are defined, in this case with ``owner`` as the ``controller``:
 
 .. literalinclude:: quickstart/template-root/daml/Iou.daml
   :language: daml
-  :lines: 23, 52-55
+  :start-after: -- BEGIN_IOU_TEMPLATE_SPLIT
+  :end-before: -- END_IOU_TEMPLATE_SPLIT
 
-``controller owner can`` starts the block. In this case, ``owner`` has the right to:
+.. literalinclude:: quickstart/template-root/daml/Iou.daml
+  :language: daml
+  :start-after: -- BEGIN_IOU_TEMPLATE_MERGE
+  :end-before: -- END_IOU_TEMPLATE_MERGE
+
+.. literalinclude:: quickstart/template-root/daml/Iou.daml
+  :language: daml
+  :start-after: -- BEGIN_IOU_TEMPLATE_TRANSFER
+  :end-before: -- END_IOU_TEMPLATE_TRANSFER
+
+.. literalinclude:: quickstart/template-root/daml/Iou.daml
+  :language: daml
+  :start-after: -- BEGIN_IOU_TEMPLATE_OBSERVER_CHOICES
+  :end-before: -- END_IOU_TEMPLATE_OBSERVER_CHOICES
+
+Thus, ``owner`` has the right to:
 
 - split the Iou
 - merge it with another one differing only on ``amount``
@@ -325,7 +345,8 @@ A more interesting choice is ``IouTrade_Accept``. To look at it, open ``IouTrade
 
 .. literalinclude:: quickstart/template-root/daml/IouTrade.daml
   :language: daml
-  :lines: 25-46
+  :start-after: -- BEGIN_IOU_COMPOSITE_CHOICE
+  :end-before: -- END_IOU_COMPOSITE_CHOICE
 
 This choice uses the ``===`` operator from the :doc:`Daml Standard Library </daml/stdlib/index>` to check pre-conditions. The standard library is imported using ``import DA.Assert`` at the top of the module.
 
@@ -352,7 +373,8 @@ The following block, for example, issues an ``Iou`` and transfers it to Alice:
 
 .. literalinclude:: quickstart/template-root/daml/Tests/Trade.daml
   :language: daml
-  :lines: 19-27
+  :start-after: -- BEGIN_SCENARIO
+  :end-before: -- END_SCENARIO
 
 Compare the scenario with the ``setup`` scenario in ``daml/Main.daml``. You will see that the scenario you used to initialize the sandbox is an initial segment of the ``trade_test`` scenario. The latter adds transactions to perform the trade you performed through Navigator, and a couple of transactions in which expectations are verified.
 

diff --git a/docs/source/app-dev/bindings-java/quickstart/template-root/daml/Iou.daml b/docs/source/app-dev/bindings-java/quickstart/template-root/daml/Iou.daml
@@ -1,26 +1,33 @@
 -- Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
 -- SPDX-License-Identifier: Apache-2.0
 
-
+-- BEGIN_IOU_MODULE_NAME
 module Iou where
+-- END_IOU_MODULE_NAME
 
 type IouCid = ContractId Iou
 
+-- BEGIN_IOU_TEMPLATE_DATATYPE
 template Iou
   with
     issuer : Party
     owner : Party
     currency : Text
     amount : Decimal
     observers : [Party]
+-- END_IOU_TEMPLATE_DATATYPE
   where
+-- BEGIN_IOU_TEMPLATE_CONDITIONS
     ensure amount > 0.0
 
     signatory issuer, owner
-
+-- END_IOU_TEMPLATE_CONDITIONS
+-- BEGIN_IOU_TEMPLATE_OBSERVERS
     observer observers
+-- END_IOU_TEMPLATE_OBSERVERS
 
       -- Split the IOU by dividing the amount.
+-- BEGIN_IOU_TEMPLATE_SPLIT
     choice Iou_Split : (IouCid, IouCid)
         with
         splitAmount: Decimal
@@ -30,8 +37,10 @@ template Iou
         splitCid <- create this with amount = splitAmount
         restCid <- create this with amount = restAmount
         return (splitCid, restCid)
+-- END_IOU_TEMPLATE_SPLIT
 
       -- Merge two IOUs by aggregating their amounts.
+-- BEGIN_IOU_TEMPLATE_MERGE
     choice Iou_Merge : IouCid
       with
         otherCid: IouCid
@@ -48,13 +57,17 @@ template Iou
         archive otherCid
         -- Return the merged Iou
         create this with amount = amount + otherIou.amount
+-- END_IOU_TEMPLATE_MERGE
 
+-- BEGIN_IOU_TEMPLATE_TRANSFER
     choice Iou_Transfer : ContractId IouTransfer
       with
         newOwner : Party
       controller owner
       do create IouTransfer with iou = this; newOwner
+-- END_IOU_TEMPLATE_TRANSFER
 
+-- BEGIN_IOU_TEMPLATE_OBSERVER_CHOICES
     choice Iou_AddObserver : IouCid
       with
         newObserver : Party
@@ -66,6 +79,7 @@ template Iou
         oldObserver : Party
       controller owner
       do create this with observers = filter (/= oldObserver) observers
+-- END_IOU_TEMPLATE_OBSERVER_CHOICES
 
 template IouTransfer
   with

diff --git a/docs/source/app-dev/bindings-java/quickstart/template-root/daml/IouTrade.daml b/docs/source/app-dev/bindings-java/quickstart/template-root/daml/IouTrade.daml
@@ -23,6 +23,7 @@ template IouTrade
     signatory buyer
     observer seller
 
+-- BEGIN_IOU_COMPOSITE_CHOICE
     choice IouTrade_Accept : (IouCid, IouCid)
       with
         quoteIouCid : IouCid
@@ -45,6 +46,7 @@ template IouTrade
           newOwner = seller
         transferredBaseIouCid <- exercise baseIouTransferCid IouTransfer_Accept
         return (transferredQuoteIouCid, transferredBaseIouCid)
+-- END_IOU_COMPOSITE_CHOICE
 
     choice TradeProposal_Reject : ()
       controller seller

diff --git a/docs/source/app-dev/bindings-java/quickstart/template-root/daml/Tests/Trade.daml b/docs/source/app-dev/bindings-java/quickstart/template-root/daml/Tests/Trade.daml
@@ -17,6 +17,7 @@ trade_test = do
   usBank <- allocateParty "USD_Bank"
   eurBank <- allocateParty "EUR_Bank"
 
+-- BEGIN_SCENARIO
   -- Banks issue IOU transfers.
   iouTransferAliceCid <- submit eurBank do
     createAndExerciseCmd
@@ -28,6 +29,7 @@ trade_test = do
         observers = []
       Iou_Transfer with
         newOwner = alice
+-- END_SCENARIO
 
   iouTransferBobCid <- submit usBank do
     createAndExerciseCmd

diff --git a/docs/source/app-dev/bindings-x-lang/index.rst b/docs/source/app-dev/bindings-x-lang/index.rst
@@ -36,7 +36,8 @@ Let's recall an **IOU** example from the :doc:`Quickstart guide </app-dev/bindin
 
 .. literalinclude:: /app-dev/bindings-java/quickstart/template-root/daml/Iou.daml
   :language: daml
-  :lines: 9-15
+  :start-after: -- BEGIN_IOU_TEMPLATE_DATATYPE
+  :end-before: -- END_IOU_TEMPLATE_DATATYPE
 
 Here is how to manually build a :ref:`com.daml.ledger.api.v1.CreateCommand` for the above contract template in Scala:
 
@@ -60,7 +61,8 @@ To build :ref:`com.daml.ledger.api.v1.ExerciseCommand` for `Iou_Transfer`:
 
 .. literalinclude:: /app-dev/bindings-java/quickstart/template-root/daml/Iou.daml
   :language: daml
-  :lines: 23, 52-55
+  :start-after: -- BEGIN_IOU_TEMPLATE_TRANSFER
+  :end-before: -- END_IOU_TEMPLATE_TRANSFER
 
 manually in Scala:
 

diff --git a/docs/source/app-dev/code-snippets/Templates.daml b/docs/source/app-dev/code-snippets/Templates.daml
@@ -4,6 +4,7 @@
 
 module Templates where
 
+-- BEGIN_SIMPLE_TEMPLATE
 data MySimpleTemplateKey =
   MySimpleTemplateKey
     with
@@ -17,6 +18,7 @@ template MySimpleTemplate
 
         key MySimpleTemplateKey owner: MySimpleTemplateKey
         maintainer key.party
+-- END_SIMPLE_TEMPLATE
 
         choice MyChoice
             : ()

diff --git a/docs/source/app-dev/grpc/daml-to-ledger-api.rst b/docs/source/app-dev/grpc/daml-to-ledger-api.rst
@@ -81,8 +81,9 @@ Contract templates are represented as records with the same identifier as the te
 This first example template below contains only the signatory party and a simple choice to exercise:
 
 .. literalinclude:: ../code-snippets/Templates.daml
-    :language: daml
-    :lines: 6-18
+  :language: daml
+  :start-after: -- BEGIN_SIMPLE_TEMPLATE
+  :end-before: -- END_SIMPLE_TEMPLATE
 
 Creating a contract
 ===================

diff --git a/docs/source/concepts/ledger-model/ledger-daml.rst b/docs/source/concepts/ledger-model/ledger-daml.rst
@@ -75,7 +75,7 @@ of a simple IOU with a unit amount, shown earlier.
 
 .. _da-daml-model-controller-observer:
 
-In this example, the owner is automatically made an observer on the contract, as the :code:`Transfer` and :code:`Settle` choices use the :code:`controller owner can` syntax.
+In this example, the owner is specified as an observer, since it must be able to see the contract to exercise the :code:`Transfer` and :code:`Settle` choices on it.
 
 The template identifiers of contracts are created
 through a content-addressing scheme. This means every contract is

diff --git a/docs/source/daml/code-snippets/Reference.daml b/docs/source/daml/code-snippets/Reference.daml
@@ -107,8 +107,9 @@ template NameOfTemplate
           do
             return ()
 
+-- deprecated syntax: 'controller ... can' will be removed in a future version of Daml.
+-- We keep it here for documentation purposes until it is removed.
 -- start controller-first controller snippet
-    -- deprecated syntax
     controller exampleParty can
 -- end controller-first controller snippet
 -- start controller-first choice name snippet

diff --git a/docs/source/daml/code-snippets/RestrictedPayout.daml b/docs/source/daml/code-snippets/RestrictedPayout.daml
@@ -33,12 +33,14 @@ template RestrictedPayout
       controller receiver
       do create Payout with receiver; giver; qty
 
+-- BEGIN_CHOICE_WITH_ASSERT
     choice Transfer : ContractId RestrictedPayout
       with newReceiver : Party
       controller receiver
       do
         assert (newReceiver /= blacklisted)
         create RestrictedPayout with receiver = newReceiver; giver; blacklisted; qty
+-- END_CHOICE_WITH_ASSERT
 
 exampleFailureBlacklisted = scenario do
     boe <- getParty "Bank of England"