From 0db0abbe49d19aafd694c19332ee2ffd96be4599 Mon Sep 17 00:00:00 2001
From: Hongrui Fang <chfanghr@gmail.com>
Date: Tue, 6 Sep 2022 21:50:48 +0800
Subject: [PATCH] document newly added validation context types

---
 agora/Agora/Proposal/Scripts.hs | 34 +++++++++++++++++++++++----------
 agora/Agora/Stake/Scripts.hs    | 12 ++++++++++--
 2 files changed, 34 insertions(+), 12 deletions(-)

diff --git a/agora/Agora/Proposal/Scripts.hs b/agora/Agora/Proposal/Scripts.hs
index 19d6893..2ddb373 100644
--- a/agora/Agora/Proposal/Scripts.hs
+++ b/agora/Agora/Proposal/Scripts.hs
@@ -134,33 +134,49 @@ proposalPolicy (AssetClass (govCs, govTn)) =
 
     pure $ popaque (pconstant ())
 
+{- | Validation context for redeemers which witness multiple stake in the reference
+      inputs.
+
+     @since 1.0.0
+-}
 data PWitneseMultipleStakeContext (s :: S) = PWitneseMultipleStakeContext
   { totalAmount :: Term s PInteger
   , orderedOwners :: Term s (PList PCredential)
   }
-  deriving stock (Generic)
+  deriving stock
+    ( -- | @since 1.0.0
+      Generic
+    )
   deriving anyclass
-    ( PlutusType
+    ( -- | @since 1.0.0
+      PlutusType
     )
 
+-- | @since 1.0.0
 instance DerivePlutusType PWitneseMultipleStakeContext where
   type DPTStrat _ = PlutusTypeScott
 
+{- | Validation context for redeemers which need to modify a single stake.
+
+     @since 1.0.0
+-}
 data PSpendSingleStakeContext (s :: S) = PSpendSingleStakeContext
   { inputStake :: Term s PStakeDatum
   , outputStake :: Term s PStakeDatum
   }
-  deriving stock (Generic)
+  deriving stock
+    ( -- | @since 1.0.0
+      Generic
+    )
   deriving anyclass
-    ( PlutusType
+    ( -- | @since 1.0.0
+      PlutusType
     )
 
+-- | @since 1.0.0
 instance DerivePlutusType PSpendSingleStakeContext where
   type DPTStrat _ = PlutusTypeScott
 
-pemptyWitneseMultipleStakeContext :: forall (s :: S). Term s PWitneseMultipleStakeContext
-pemptyWitneseMultipleStakeContext = pcon $ PWitneseMultipleStakeContext 0 pnil
-
 {- | The validator for Proposals.
 
      The documentation for various of the redeemers lives at 'Agora.Proposal.ProposalRedeemer'.
@@ -293,8 +309,6 @@ proposalValidator as maximumCosigners =
 
     onlyStatusChanged <-
       pletC $
-        -- Only the status of proposals is updated.
-
         -- Only the status of proposals is updated.
         proposalOut
           #== mkRecordConstr
@@ -376,7 +390,7 @@ proposalValidator as maximumCosigners =
               sortOwners
                 #$ pfoldl
                 # f
-                # pemptyWitneseMultipleStakeContext
+                # pcon (PWitneseMultipleStakeContext 0 pnil)
                 # txInfoF.referenceInputs
          in plam (# ctx)
 
diff --git a/agora/Agora/Stake/Scripts.hs b/agora/Agora/Stake/Scripts.hs
index 3ca8146..da8ed3a 100644
--- a/agora/Agora/Stake/Scripts.hs
+++ b/agora/Agora/Stake/Scripts.hs
@@ -197,6 +197,11 @@ stakePolicy gtClassRef =
 
 --------------------------------------------------------------------------------
 
+{- | Validation context for stake redeemers that allow only one stake to be
+      spent in the transaction.
+
+     @since 1.0.0
+-}
 data POnlyOneStakeContext (s :: S) = POnlyOneStakeContext
   { ownOutputDatum :: Term s PStakeDatum
   , ownOutputValue :: Term s (PValue 'Sorted 'Positive)
@@ -204,12 +209,15 @@ data POnlyOneStakeContext (s :: S) = POnlyOneStakeContext
   , onlyLocksUpdated :: Term s PBool
   }
   deriving stock
-    ( Generic
+    ( -- | @since 1.0.0
+      Generic
     )
   deriving anyclass
-    ( PlutusType
+    ( -- | @since 1.0.0
+      PlutusType
     )
 
+-- | @since 1.0.0
 instance DerivePlutusType POnlyOneStakeContext where
   type DPTStrat _ = PlutusTypeScott