apply docs suggestions

agora.cabal

@@ -96,6 +96,7 @@ common deps
     , generics-sop
     , plutarch
     , plutarch-extra
+    , plutarch-numeric
     , plutus-core
     , plutus-ledger-api
     , plutus-tx

agora/Agora/Governor.hs

@@ -5,7 +5,7 @@ Description: Governor entity scripts acting as authority of entire system.
 
 Governor entity scripts acting as authority of entire system.
 -}
-module Agora.Governor (GovernorDatum (..), GovernorRedeemer (..)) where
+module Agora.Governor (GovernorDatum (..), GovernorRedeemer (..), Governor (..)) where
 
 import Agora.Proposal (ProposalThresholds)
 
@@ -15,11 +15,11 @@ newtype GovernorDatum = GovernorDatum
   -- ^ Gets copied over upon creation of a 'Agora.Proposal.ProposalDatum'.
   }
 
-{- | Redeemer for Governor script.
+{- | Redeemer for Governor script. The governor has two primary
+     responsibilities:
 
-     The governor has two primary responsibilities:
-     - The gating of Proposal creation
-     - The gating of minting authority tokens
+     1. The gating of Proposal creation.
+     2. The gating of minting authority tokens.
 -}
 data GovernorRedeemer
   = -- | Checks that a proposal was created lawfully, and allows it.
@@ -27,3 +27,7 @@ data GovernorRedeemer
   | -- | Checks that a SINGLE proposal finished correctly,
     --   and allows minting GATs for each effect script.
     MintGATs
+
+-- | Parameters for creating Governor scripts.
+data Governor
+  = Governor

agora/Agora/Proposal.hs

@@ -88,12 +88,12 @@ data ProposalStatus
 PlutusTx.makeIsDataIndexed ''ProposalStatus [('Draft, 0), ('VotingReady, 1), ('Finished, 2)]
 
 {- | The threshold values for various state transitions to happen.
-     This data is stored centrally (in the Governor) and copied over
-     to Proposals when they are created.
+     This data is stored centrally (in the 'Agora.Governor.Governor') and copied over
+     to 'Proposal's when they are created.
 -}
 data ProposalThresholds = ProposalThresholds
   { execute :: Discrete GTTag
-  -- ^ How much GT minimum must a particular 'ResultTag' accumulate to fulfil.
+  -- ^ How much GT minimum must a particular 'ResultTag' accumulate for it to pass.
   , draft :: Discrete GTTag
   -- ^ How much GT required to "create" a proposal.
   , vote :: Discrete GTTag
@@ -110,7 +110,7 @@ PlutusTx.makeIsDataIndexed ''ProposalThresholds [('ProposalThresholds, 0)]
 
    @[('ResultTag' 0, []), ('ResultTag' 1, [(vh, dh)])]@
 
-   Then 'ProposalVotes' need be of the shape:
+   Then 'ProposalVotes' needs be of the shape:
 
    @[('ResultTag' 0, n), ('ResultTag' 1, m)]@
 -}
@@ -125,11 +125,11 @@ data ProposalDatum = ProposalDatum
   -- This is shaped this way for future proofing.
   -- See https://github.com/Liqwid-Labs/agora/issues/39
   effects :: [(ResultTag, [(ValidatorHash, DatumHash)])]
-  -- ^ Effect lookup table. First by result, then by
+  -- ^ Effect lookup table. First by result, then by effect hash.
   , status :: ProposalStatus
   -- ^ The status the proposal is in.
   , cosigners :: [PubKeyHash]
-  -- ^ Who created the proposal initially + who cosigned.
+  -- ^ Who created the proposal initially, and who cosigned it later.
   , thresholds :: ProposalThresholds
   -- ^ Thresholds copied over on initialization.
   , votes :: ProposalVotes

agora/Agora/Stake.hs

@@ -83,7 +83,7 @@ import Agora.Utils (
 -- | Parameters for creating Stake scripts.
 newtype Stake = Stake
   { gtClassRef :: AssetClassRef GTTag
-  -- ^ Resolve governance token
+  -- ^ Used when inlining the AssetClass of a 'PDiscrete' in the script code.
   }
 
 -- | Plutarch-level redeemer for Stake scripts.