From 18dce71f72d44bcfcc3c207a2312f2e0cfd599b8 Mon Sep 17 00:00:00 2001
From: fanghr <chfanghr@gmail.com>
Date: Sat, 23 Apr 2022 16:21:23 +0800
Subject: [PATCH] doc string for util functions

---
 agora.cabal          |  3 ---
 agora/Agora/Utils.hs | 13 +++++++++----
 2 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/agora.cabal b/agora.cabal
index 9edb978..b55630b 100644
--- a/agora.cabal
+++ b/agora.cabal
@@ -159,10 +159,7 @@ test-suite agora-test
   hs-source-dirs: agora-test
   other-modules:
     Spec.AuthorityToken
-<<<<<<< HEAD
     Spec.Effect.TreasuryWithdrawal
-=======
->>>>>>> 0f1b4f3 (rewrite the doc for governor components)
     Spec.Model.MultiSig
     Spec.Proposal
     Spec.Sample.Effect.TreasuryWithdrawal
diff --git a/agora/Agora/Utils.hs b/agora/Agora/Utils.hs
index 9d4ca86..9eb0945 100644
--- a/agora/Agora/Utils.hs
+++ b/agora/Agora/Utils.hs
@@ -510,7 +510,6 @@ findTxOutDatum = phoistAcyclic $
       PDJust ((pfield @"_0" #) -> datumHash) -> pfindDatum # datumHash # datums
       _ -> pcon PNothing
 
-<<<<<<< HEAD
 {- | Safely convert a 'PValidatorHash' into a 'PTokenName'. This can be useful for tagging
      tokens for extra safety.
 -}
@@ -525,8 +524,7 @@ pvalidatorHashToTokenName vh = pcon (PTokenName (pto vh))
 getMintingPolicySymbol :: ClosedTerm PMintingPolicy -> CurrencySymbol
 getMintingPolicySymbol v = mintingPolicySymbol $ mkMintingPolicy v
 
-=======
->>>>>>> 93fe9ca (fix compilation erros; format && lint)
+-- | The entire value only contains one token of the specific assetclass.
 hasOnlyOneTokenOfAssetClass' :: AssetClass -> Term s (PValue :--> PBool)
 hasOnlyOneTokenOfAssetClass' ac@(AssetClass (as, _)) = phoistAcyclic $
   plam $ \vs -> P.do
@@ -536,13 +534,14 @@ hasOnlyOneTokenOfAssetClass' ac@(AssetClass (as, _)) = phoistAcyclic $
       #&& passetClassValueOf' ac # vs #== 1
       #&& (plength #$ pto $ pto $ pto vs) #== 1
 
+-- | The entire value only contains one token of the specific currency symbol.
 hasOnlyOneTokenOfCurrencySymbol :: Term s (PCurrencySymbol :--> PValue :--> PBool)
 hasOnlyOneTokenOfCurrencySymbol = phoistAcyclic $
   plam $ \cs vs -> P.do
     psymbolValueOf # cs # vs #== 1
       #&& (plength #$ pto $ pto $ pto vs) #== 1
 
-{- Find datum, in an unsafe manner.
+{- Find datum given a maybe datum hash, in an unsafe manner.
 
    FIXME: reimplement using 'ptryFrom'.
 -}
@@ -556,12 +555,18 @@ mustFindDatum' = phoistAcyclic $
     PJust dt <- pmatch $ pfindDatum # dh # info
     pfromData $ punsafeCoerce dt
 
+{- | Extract the value stored in a PMaybe container. 
+     If there's no value, throw an error with the given message.
+-}
 mustBePJust :: forall a s. Term s (PString :--> PMaybe a :--> a)
 mustBePJust = phoistAcyclic $
   plam $ \emsg mv' -> pmatch mv' $ \case
     PJust v -> v
     _ -> ptraceError emsg
 
+{- | Extract the value stored in a PMaybeData container. 
+     If there's no value, throw an error with the given message.
+-}
 mustBePDJust :: forall a s. (PIsData a) => Term s (PString :--> PMaybeData a :--> a)
 mustBePDJust = phoistAcyclic $
   plam $ \emsg mv' -> pmatch mv' $ \case