Generate API docs for DAML script and include them in the SDK docs (d…

…igital-asset#3568) * Generate API docs for DAML script and include them in the SDK docs * Update daml-script/daml/Daml/Script.daml Co-Authored-By: Martin Huschenbett <martin.huschenbett@posteo.me>
kgeonw · Nov 21, 2019 · ec5d832 · ec5d832
1 parent 55dfe96
commit ec5d832
Show file tree

Hide file tree

Showing 5 changed files with 67 additions and 2 deletions.
diff --git a/daml-script/daml/BUILD.bazel b/daml-script/daml/BUILD.bazel
@@ -28,3 +28,19 @@ EOF
     tools = ["//compiler/damlc"],
     visibility = ["//visibility:public"],
 )
+
+genrule(
+    name = "daml-script-rst-docs",
+    srcs = glob(["**/*.daml"]) + [":daml-script-rst-template.rst"],
+    outs = ["daml-script.rst"],
+    cmd = """
+        $(location //compiler/damlc) -- docs \
+            --combine \
+            --output=$(location :daml-script.rst) \
+            --format=Rst \
+            --template=$(location :daml-script-rst-template.rst) \
+            $(location Daml/Script.daml)
+    """,
+    tools = ["//compiler/damlc"],
+    visibility = ["//visibility:public"],
+)
diff --git a/daml-script/daml/Daml/Script.daml b/daml-script/daml/Daml/Script.daml
@@ -2,8 +2,18 @@
 -- SPDX-License-Identifier: Apache-2.0
 
 daml 1.2
-module Daml.Script where
-
+module Daml.Script
+  ( Script
+  , submit
+  , submitMustFail
+  , query
+  , allocateParty
+  , Commands
+  , createCmd
+  , exerciseCmd
+  ) where
+
+import Prelude hiding (submit, submitMustFail)
 import DA.Optional
 
 -- | A free monad
@@ -45,6 +55,11 @@ data CommandsF a
   | Exercise { tplId : TemplateTypeRep, cId : ContractId (), argE : AnyChoice, continueE : LedgerValue -> a }
   deriving Functor
 
+-- | This is used to build up the commands send as part of `submit`.
+-- If you enable the `ApplicativeDo` extension by adding
+-- `{-# LANGUAGE ApplicativeDo #-}` at the top of your file, you can
+-- use `do`-notation but the individual commands must not depend
+-- on each other.
 newtype Commands a = Commands (Ap CommandsF a)
   deriving (Functor, Applicative)
 
@@ -60,6 +75,8 @@ data QueryACS a = QueryACS
   , continue : [(ContractId (), AnyTemplate)] -> a
   } deriving Functor
 
+-- | Query the set of active contracts of the template
+-- that are visible to the given party.
 query : forall t. Template t => Party -> Script [(ContractId t, t)]
 query p = Script $ Free $ Query (QueryACS p (templateTypeRep @t) (pure . map (\(cid, tpl) -> (coerceContractId cid, fromSome $ fromAnyTemplate tpl))))
 
@@ -68,6 +85,8 @@ data AllocateParty a = AllocateParty
   , continue : Party -> a
   } deriving Functor
 
+-- | Allocate a party with the given display name
+-- using the party management service.
 allocateParty : Text -> Script Party
 allocateParty displayName = Script $ Free (AllocParty $ AllocateParty displayName pure)
 
@@ -79,14 +98,22 @@ data SubmitFailure = SubmitFailure
 data SubmitCmd a = SubmitCmd { party : Party, commands : Commands a, handleFailure : SubmitFailure -> a }
   deriving Functor
 
+-- | Submit the commands as a single transaction.
+
+-- This will error if the submission fails.
 submit : Party -> Commands a -> Script a
 submit p cmds = Script $ Free (fmap pure $ Submit $ SubmitCmd p cmds fail)
   where fail (SubmitFailure status msg) = error $ "Submit failed with code " <> show status <> ": " <> msg
 
+-- | Submit the commands as a single transaction
+-- but error if it succeeds. This is only
+-- useful for testing.
 submitMustFail : Party -> Commands a -> Script ()
 submitMustFail p cmds = Script $ Free (fmap pure $ Submit $ SubmitCmd p (fail <$> cmds) (const ()))
   where fail _ = error "Expected submit to fail but it succeeded"
 
+-- | This is the type of A DAML script. `Script` is an instance of `Action`,
+-- so you can use `do` notation.
 newtype Script a = Script (Free ScriptF a)
   deriving (Functor, Applicative, Action)
 
@@ -98,8 +125,10 @@ data LedgerValue = LedgerValue {}
 fromLedgerValue : LedgerValue -> a
 fromLedgerValue = error "foobar"
 
+-- | Create a contract of the given template.
 createCmd : Template t => t -> Commands (ContractId t)
 createCmd arg = Commands $ Ap (\f -> f (Create (toAnyTemplate arg) identity) (pure coerceContractId))
 
+-- | Exercise a choice on the given contract.
 exerciseCmd : forall t c r. Choice t c r => ContractId t -> c -> Commands r
 exerciseCmd cId arg = Commands $ Ap (\f -> f (Exercise (templateTypeRep @t) (coerceContractId cId) (toAnyChoice @t arg) identity) (pure fromLedgerValue))
diff --git a/daml-script/daml/daml-script-rst-template.rst b/daml-script/daml/daml-script-rst-template.rst
@@ -0,0 +1,11 @@
+.. Copyright (c) 2019 The DAML Authors. All rights reserved.
+.. SPDX-License-Identifier: Apache-2.0
+
+.. _daml-script-api-docs:
+
+DAML Script Library
+====================
+
+The DAML Script library defines the API used to implement DAML scripts. See :doc:`index`:: for more information on DAML script.
+
+{{{body}}}
diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel
@@ -80,6 +80,7 @@ genrule(
     srcs = glob(["source/**"]) + [
         "//compiler/damlc:daml-base-rst-docs",
         "//triggers/daml:daml-trigger-rst-docs",
+        "//daml-script/daml:daml-script-rst-docs",
         "//ledger-api/grpc-definitions:docs",
         "//:LICENSE",
         "//:NOTICES",
@@ -94,6 +95,9 @@ genrule(
         # Copy in daml-trigger documentation
         cp -rL $(location //triggers/daml:daml-trigger-rst-docs) source/triggers/trigger-docs.rst
 
+        # Copy in daml-script documentation
+        cp -rL $(location //daml-script/daml:daml-script-rst-docs) source/daml-script/daml-script-docs.rst
+
         # Copy in Protobufs
         cp -rL $(location //ledger-api/grpc-definitions:docs) source/app-dev/grpc/proto-docs.rst
 

diff --git a/docs/source/daml-script/index.rst b/docs/source/daml-script/index.rst
@@ -4,6 +4,11 @@
 DAML Script
 ###########
 
+.. toctree::
+   :hidden:
+
+   daml-script-docs
+
 **WARNING:** DAML Script is an experimental feature that is actively
 being designed and is *subject to breaking changes*.
 We welcome feedback about DAML script on