Improve docs around the new Template, Choice, TemplateKey constraints. (#4069)

* Try to improve the docs on DA.Internal.Template.Functions a little.

* More docs.

changelog_begin

- [DAML Standard Library] The ``Template``, ``Choice``, and
``TemplateKey`` typeclasses have been split up into many small typeclasses
to improve forward compatibility of DAML models. ``Template``,
``Choice`` and ``TemplateKey`` constraints can still be used as before.

changelog_end

* Example typo

compiler/damlc/daml-stdlib-src/DA/Internal/Template/Functions.daml

@@ -25,7 +25,7 @@ import DA.Internal.Template
 import GHC.Types (primitive)
 #endif
 
--- | Constraints satisfied by template types.
+-- | Constraint satisfied by templates.
 type Template t =
   ( HasSignatory t
   , HasObserver t
@@ -39,51 +39,66 @@ type Template t =
   , HasFromAnyTemplate t
   )
 
+-- | Exposes `signatory` function. Part of the `Template` constraint.
 class HasSignatory t where
   -- | The signatories of a contract.
   signatory : t -> [Party]
 
+-- | Exposes `observer` function. Part of the `Template` constraint.
 class HasObserver t where
   -- | The observers of a contract.
   observer : t -> [Party]
 
+-- | Exposes `ensure` function. Part of the `Template` constraint.
 class HasEnsure t where
   -- | A predicate that must be true, otherwise contract creation will fail.
   ensure : t -> Bool
 
+-- | Exposes `agreement` function. Part of the `Template` constraint.
 class HasAgreement t where
   -- | The agreement text of a contract.
   agreement : t -> Text
 
+-- | Exposes `create` function. Part of the `Template` constraint.
 class HasCreate t where
   -- | Create a contract based on a template `t`.
   create : t -> Update (ContractId t)
 
+-- | Exposes `fetch` function. Part of the `Template` constraint.
 class HasFetch t where
   -- | Fetch the contract data associated with the given contract ID.
   -- If the `ContractId t` supplied is not the contract ID of an active
   -- contract, this fails and aborts the entire transaction.
   fetch : ContractId t -> Update t
 
+-- | Exposes `archive` function. Part of the `Template` constraint.
 class HasArchive t where
   -- | Archive the contract with the given contract ID.
   archive : ContractId t -> Update ()
 
+-- | Exposes `templateTypeRep` function in DAML-LF 1.7 or later.
+-- Part of the `Template` constraint.
 class HasTemplateTypeRep t where
-  -- | Generate a unique textual representation of the template Id.
+  -- | HIDE
   _templateTypeRep : proxy t -> TypeRep
 
+-- | Exposes `toAnyTemplate` function in DAML-LF 1.7 or later.
+-- Part of the `Template` constraint.
 class HasToAnyTemplate t where
+  -- | HIDE
   _toAnyTemplate : t -> Any
 
+-- | Exposes `fromAnyTemplate` function in DAML-LF 1.7 or later.
+-- Part of the `Template` constraint.
 class HasFromAnyTemplate t where
+  -- | HIDE
   _fromAnyTemplate : Any -> Optional t
 
 -- | The stakeholders of a contract: its signatories and observers.
 stakeholder : (HasSignatory t, HasObserver t) => t -> [Party]
 stakeholder t = signatory t ++ observer t
 
--- | Constraints satisfied by template choice types.
+-- | Constraint satisfied by choices.
 type Choice t c r =
   ( Template t
   , HasExercise t c r
@@ -91,17 +106,24 @@ type Choice t c r =
   , HasFromAnyChoice t c r
   )
 
+-- | Exposes `exercise` function. Part of the `Choice` constraint.
 class HasExercise t c r | t c -> r where
   -- | Exercise a choice on the contract with the given contract ID.
   exercise : ContractId t -> c -> Update r
 
+-- | Exposes `toAnyChoice` function for DAML-LF 1.7 or later.
+-- Part of the `Choice` constraint.
 class HasToAnyChoice t c r | t c -> r where
+  -- | HIDE
   _toAnyChoice : proxy t -> c -> Any
 
+-- | Exposes `fromAnyChoice` function for DAML-LF 1.7 or later.
+-- Part of the `Choice` constraint.
 class HasFromAnyChoice t c r | t c -> r where
+  -- | HIDE
   _fromAnyChoice : proxy t -> Any -> Optional c
 
--- | Constrants satisfied by template key types.
+-- | Constraint satisfied by template keys.
 type TemplateKey t k =
   ( Template t
   , HasKey t k
@@ -112,10 +134,12 @@ type TemplateKey t k =
   , HasFromAnyContractKey t k
   )
 
+-- | Exposes `key` function. Part of the `TemplateKey` constraint.
 class HasKey t k | t -> k where
   -- | The key of a contract.
   key : t -> k
 
+-- | Exposes `lookupByKey` function. Part of the `TemplateKey` constraint.
 class HasLookupByKey t k | t -> k where
   -- | Look up the contract ID `t` associated with a given contract key `k`.
   --
@@ -124,6 +148,7 @@ class HasLookupByKey t k | t -> k where
   -- key `k`, you must call `lookupByKey @Account k`.
   lookupByKey : k -> Update (Optional (ContractId t))
 
+-- | Exposes `fetchByKey` function. Part of the `TemplateKey` constraint.
 class HasFetchByKey t k | t -> k where
   -- | Fetch the contract ID and contract data associated with a given
   -- contract key.
@@ -145,18 +170,25 @@ class HasFetchByKey t k | t -> k where
   --    stakeholders of the fetched contract are, which requires
   --    getting the contract instance.
 
+-- | Exposes `maintainer` function. Part of the `TemplateKey` constraint.
 class HasMaintainer t k | t -> k where
-  -- | The list of maintainers of a contract key.
+  -- | HIDE
   _maintainer : proxy t -> k -> [Party]
 
 -- | The list of maintainers of a contract key.
 maintainer : forall t k. HasMaintainer t k => k -> [Party]
 maintainer = _maintainer ([] : [t])
 
+-- | Exposes `toAnyContractKey` function in DAML-LF 1.7 or later.
+-- Part of the `TemplateKey` constraint.
 class HasToAnyContractKey t k | t -> k where
+  -- | HIDE
   _toAnyContractKey : proxy t -> k -> Any
 
+-- | Exposes `fromAnyContractKey` function in DAML-LF 1.7 or later.
+-- Part of the `TemplateKey` constraint.
 class HasFromAnyContractKey t k | t -> k where
+  -- | HIDE
   _fromAnyContractKey : proxy t -> Any -> Optional k
 
 -- | Exercise a choice on the contract associated with the given key.
@@ -216,7 +248,7 @@ instance Eq AnyContractKey where
 
 #ifdef DAML_TYPE_REP
 
--- | Generate a unique textual representation of the template Id.
+-- | Generate a unique textual representation of the template id.
 templateTypeRep : forall t. HasTemplateTypeRep t => TemplateTypeRep
 templateTypeRep = TemplateTypeRep (_templateTypeRep ([] : [t]))
 
@@ -225,34 +257,64 @@ instance Eq TemplateTypeRep where
 
 #ifdef DAML_ANY_TYPE
 
--- | Wrap the template in AnyTemplate
+-- | Wrap the template in `AnyTemplate`.
+--
+-- Only available for DAML-LF 1.7 or later.
 toAnyTemplate : HasToAnyTemplate t => t -> AnyTemplate
 toAnyTemplate x = AnyTemplate (_toAnyTemplate x)
 
--- | Extract the underlying template from AnyTemplate if the type matches
+-- | Extract the underlying template from `AnyTemplate` if the type matches
 -- or return `None`.
+--
+-- Only available for DAML-LF 1.7 or later.
 fromAnyTemplate : HasFromAnyTemplate t => AnyTemplate -> Optional t
 fromAnyTemplate (AnyTemplate x) = _fromAnyTemplate x
 
-toAnyChoice : forall t c r. Choice t c r => c -> AnyChoice
+-- | Wrap a choice in `AnyChoice`.
+--
+-- You must pass the template type `t` using an explicit type application.
+-- For example `toAnyChoice @Account Withdraw`.
+--
+-- Only available for DAML-LF 1.7 or later.
+toAnyChoice : forall t c r. (HasTemplateTypeRep t, HasToAnyChoice t c r) => c -> AnyChoice
 toAnyChoice c =
   AnyChoice
     (_toAnyChoice ([] : [t]) c)
     (templateTypeRep @t)
 
-fromAnyChoice : forall t c r. Choice t c r => AnyChoice -> Optional c
+-- | Extract the underlying choice from `AnyChoice` if the template and
+-- choice types match, or return `None`.
+--
+-- You must pass the template type `t` using an explicit type application.
+-- For example `fromAnyChoice @Account choice`.
+--
+-- Only available for DAML-LF 1.7 or later.
+fromAnyChoice : forall t c r. (HasTemplateTypeRep t, HasFromAnyChoice t c r) => AnyChoice -> Optional c
 fromAnyChoice (AnyChoice any typeRep)
   | Some c <- _fromAnyChoice ([] : [t]) any
   , templateTypeRep @t == typeRep = Some c
   | otherwise = None
 
-toAnyContractKey : forall t k. TemplateKey t k => k -> AnyContractKey
+-- | Wrap a contract key in `AnyContractKey`.
+--
+-- You must pass the template type `t` using an explicit type application.
+-- For example `toAnyContractKey @Proposal k`.
+--
+-- Only available for DAML-LF 1.7 or later.
+toAnyContractKey : forall t k. (HasTemplateTypeRep t, HasToAnyContractKey t k) => k -> AnyContractKey
 toAnyContractKey k =
   AnyContractKey
     (_toAnyContractKey ([] : [t]) k)
     (templateTypeRep @t)
 
-fromAnyContractKey : forall t k. TemplateKey t k => AnyContractKey -> Optional k
+-- | Extract the underlying key from `AnyContractKey` if the template and
+-- choice types match, or return `None`.
+--
+-- You must pass the template type `t` using an explicit type application.
+-- For example `fromAnyContractKey @Proposal k`.
+--
+-- Only available for DAML-LF 1.7 or later.
+fromAnyContractKey : forall t k. (HasTemplateTypeRep t, HasFromAnyContractKey t k) => AnyContractKey -> Optional k
 fromAnyContractKey (AnyContractKey any rep)
   | Some k <- _fromAnyContractKey ([] : [t]) any
   , templateTypeRep @t == rep = Some k