From 0e397d2a897e8a967827c1e94385b7a7f4de8b6a Mon Sep 17 00:00:00 2001
From: fanghr <chfanghr@gmail.com>
Date: Tue, 19 Apr 2022 22:35:42 +0800
Subject: [PATCH] add doc string for `governorValidator` and `pnextProposalId`

---
 agora/Agora/Governor.hs | 23 +++++++++++++++++++++--
 agora/Agora/Proposal.hs |  2 +-
 2 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/agora/Agora/Governor.hs b/agora/Agora/Governor.hs
index 4838e7c..3ca8269 100644
--- a/agora/Agora/Governor.hs
+++ b/agora/Agora/Governor.hs
@@ -124,7 +124,7 @@ PlutusTx.makeIsDataIndexed
 -- | Parameters for creating Governor scripts.
 data Governor = Governor
   { stORef :: TxOutRef
-  -- ^ The state token that identifies the governor datum will be minted using this utxo.
+  -- ^ An utxo, which will be spent to mint the state token for the governor validator.
   , gatSymbol :: CurrencySymbol
   -- ^ The symbol of the Governance Authority Token.
   }
@@ -200,7 +200,26 @@ governorPolicy params =
 
     popaque (pconstant ())
 
--- | Validator for Governors.
+{- Validator for Governors.
+
+   A state token, minted by 'governorPolicy' is used to identify the datum utxo.
+
+   No matter what redeemer it receives, it will always check:
+    - The utxo which has the state token must be spent.
+    - The state token always stays at the script address.
+    - The utxo which holds the state token, has a well well-formed 'GovernorDatum' datum.
+
+   For 'CreateProposal' redeemer, it will check:
+    - Exactly one proposal token is minted.
+    - The datum which is corresponding to the proposal token must be correct.
+    - Proposal id in the governor datum must be advanced.
+
+   TODO: PMintGATs
+
+   For 'PMutateGovernor', it will check:
+    - A GAT is burnt.
+    - Said GAT must be tagged by the effect that is spending it.
+-}
 governorValidator :: Governor -> ClosedTerm PValidator
 governorValidator params =
   plam $ \datum' redeemer' ctx' -> P.do
diff --git a/agora/Agora/Proposal.hs b/agora/Agora/Proposal.hs
index f8d36e9..ef50e33 100644
--- a/agora/Agora/Proposal.hs
+++ b/agora/Agora/Proposal.hs
@@ -439,6 +439,6 @@ proposalDatumValid proposal =
         ]
 
 --------------------------------------------------------------------------------
-
+-- | Get next proposal id.
 pnextProposalId :: Term s (PProposalId :--> PProposalId)
 pnextProposalId = phoistAcyclic $ plam $ \(pto -> pid) -> pcon $ PProposalId $ pid + 1