add and fix haddock doc comments

agora-specs/Sample/Effect/TreasuryWithdrawal.hs

@@ -87,6 +87,7 @@ inputGAT =
       , txOutDatumHash = Just (DatumHash "")
       }
 
+-- | Create an input given the index of the treasury and the 'Value' at this input.
 inputTreasury :: Int -> Value -> TxInInfo
 inputTreasury indx val =
   TxInInfo
@@ -97,6 +98,7 @@ inputTreasury indx val =
       , txOutDatumHash = Just (DatumHash "")
       }
 
+-- | Create a input given the index of the user and the 'Value' at this input.
 inputUser :: Int -> Value -> TxInInfo
 inputUser indx val =
   TxInInfo
@@ -107,6 +109,7 @@ inputUser indx val =
       , txOutDatumHash = Just (DatumHash "")
       }
 
+-- | Create a input representing the collateral given by a user.
 inputCollateral :: Int -> TxInInfo
 inputCollateral indx =
   TxInInfo -- Initiator
@@ -117,6 +120,7 @@ inputCollateral indx =
       , txOutDatumHash = Just (DatumHash "")
       }
 
+-- | Create an output at the nth treasury with the given 'Value'.
 outputTreasury :: Int -> Value -> TxOut
 outputTreasury indx val =
   TxOut
@@ -125,6 +129,7 @@ outputTreasury indx val =
     , txOutDatumHash = Nothing
     }
 
+-- | Create an output at the nth user with the given 'Value'.
 outputUser :: Int -> Value -> TxOut
 outputUser indx val =
   TxOut
@@ -133,6 +138,7 @@ outputUser indx val =
     , txOutDatumHash = Nothing
     }
 
+-- | Create a list of the outputs that are required as encoded in 'TreasuryWithdrawalDatum'.
 buildReceiversOutputFromDatum :: TreasuryWithdrawalDatum -> [TxOut]
 buildReceiversOutputFromDatum (TreasuryWithdrawalDatum xs _) = f <$> xs
   where
@@ -147,7 +153,7 @@ buildReceiversOutputFromDatum (TreasuryWithdrawalDatum xs _) = f <$> xs
 validator :: Validator
 validator = mkValidator $ treasuryWithdrawalValidator currSymbol
 
--- | 'TokenName' that represents the hash of the 'Stake' validator.
+-- | 'TokenName' that represents the hash of the 'Agora.Stake.Stake' validator.
 validatorHashTN :: TokenName
 validatorHashTN = let ValidatorHash vh = validatorHash validator in TokenName vh
 

agora-specs/Spec/AuthorityToken.hs

@@ -69,6 +69,7 @@ singleAuthorityTokenBurnedTest mint outs =
           perror
    in compile s
 
+-- | The SpecificationTree exported by this module.
 specs :: [SpecificationTree]
 specs =
   [ -- This is better suited for plutarch-test

agora-specs/Spec/Governor.hs

@@ -28,6 +28,7 @@ import Test.Specification (
 
 --------------------------------------------------------------------------------
 
+-- | The SpecificationTree exported by this module.
 specs :: [SpecificationTree]
 specs =
   [ group

agora-specs/Spec/Stake.hs

@@ -34,6 +34,7 @@ import Test.Util (toDatum)
 
 --------------------------------------------------------------------------------
 
+-- | The SpecificationTree exported by this module.
 specs :: [SpecificationTree]
 specs =
   [ group

agora-testlib/Test/Util.hs

@@ -34,11 +34,11 @@ import PlutusTx.Ord qualified as PlutusTx
 
 --------------------------------------------------------------------------------
 
-{- | Create a pair from data for use in 'txInfoData'.
+{- | Create a pair from data for use in 'Plutus.V1.Ledger.Contexts.txInfoData'.
 
    Example:
    @
-     myTxInfo { 'txInfoData' = ['datumPair' myDatum] }
+     myTxInfo { 'Plutus.V1.Ledger.Contexts.txInfoData' = ['datumPair' myDatum] }
    @
 -}
 datumPair :: PlutusTx.ToData a => a -> (DatumHash, Datum)

agora/Agora/Governor.hs

@@ -183,6 +183,7 @@ getNextProposalId (ProposalId pid) = ProposalId $ pid + 1
 
 --------------------------------------------------------------------------------
 
+-- | Check whether a particular 'PGovernorDatum' is well-formed.
 governorDatumValid :: Term s (PGovernorDatum :--> PBool)
 governorDatumValid = phoistAcyclic $
   plam $ \datum -> unTermCont $ do

agora/Agora/Governor/Scripts.hs

@@ -203,15 +203,15 @@ governorPolicy gov =
 
     - The UTXO which holds the GST must be spent.
     - The GST always stays at the validator's address.
-    - The new state UTXO has a valid datum of type 'GovernorDatum'.
+    - The new state UTXO has a valid datum of type 'Agora.Governor.GovernorDatum'.
 
   == Creating a Proposal
 
-  When the redeemer is 'CreateProposal', the script will check:
+  When the redeemer is 'Agora.Governor.CreateProposal', the script will check:
 
   - For governor's state datum:
 
-      * 'nextProposalId' is advanced.
+      * 'Agora.Governor.nextProposalId' is advanced.
       * Nothing is changed other that that.
 
   - Exactly one stake (the "input stake") must be provided in the input:
@@ -236,7 +236,7 @@ governorPolicy gov =
 
   == Minting GATs
 
-  When the redeemer is 'MintGATs', the script will check:
+  When the redeemer is 'Agora.Governor.MintGATs', the script will check:
 
   - Governor's state is not changed.
   - Exactly only one proposal is in the inputs. Let's call this the /input proposal/.
@@ -272,7 +272,7 @@ governorPolicy gov =
 
   == Changing the State
 
-  Redeemer 'MutateGovernor' allows the state datum to be changed by an external effect.
+  Redeemer 'Agora.Governor.MutateGovernor' allows the state datum to be changed by an external effect.
 
   In this case, the script will check
 

agora/Agora/Proposal.hs

@@ -352,7 +352,7 @@ deriving via
   instance
     (PConstantDecl ProposalVotes)
 
--- Plutarch-level version of 'emptyVotesFor'.
+-- | Plutarch-level version of 'emptyVotesFor'.
 pemptyVotesFor :: forall s a. (PIsData a) => Term s (PMap PResultTag a :--> PProposalVotes)
 pemptyVotesFor =
   phoistAcyclic $
@@ -451,7 +451,7 @@ proposalDatumValid proposal =
           , ptraceIfFalse "Proposal votes and effects are compatible with each other" $ pkeysEqual # datum.effects # pto (pfromData datum.votes)
           ]
 
-{- Find the winner result tag, given the votes, the quorum the "neutral" result tag.
+{- | Find the winner result tag, given the votes, the quorum the "neutral" result tag.
 
    The winner should be unambiguous, meaning that if two options have the same highest votes,
      the "neutral" option will be the winner.

agora/Agora/Proposal/Time.hs

@@ -83,7 +83,7 @@ data ProposalTimingConfig = ProposalTimingConfig
 
 PlutusTx.makeIsDataIndexed ''ProposalTimingConfig [('ProposalTimingConfig, 0)]
 
--- | Represents the maximum width of a 'POSIXTimeRange'.
+-- | Represents the maximum width of a 'Plutus.V1.Ledger.Time.POSIXTimeRange'.
 newtype MaxTimeRangeWidth = MaxTimeRangeWidth {getMaxWidth :: POSIXTime}
   deriving stock (Eq, Show, Ord, GHC.Generic)
   deriving newtype (PlutusTx.ToData, PlutusTx.FromData, PlutusTx.UnsafeFromData)
@@ -101,15 +101,19 @@ newtype MaxTimeRangeWidth = MaxTimeRangeWidth {getMaxWidth :: POSIXTime}
    determine if we are able to perform certain actions, we need to know what
    time it roughly is, compared to when the proposal was created.
 
-   'ProposalTime' represents "the time according to the proposal".
+   'PProposalTime' represents "the time according to the proposal".
    Its representation is opaque, and doesn't matter.
 
-   Various functions work simply on 'ProposalTime' and 'ProposalTimingConfig'.
+   Various functions work simply on 'PProposalTime' and 'ProposalTimingConfig'.
    In particular, 'currentProposalTime' is useful for extracting the time
    from the 'Plutus.V1.Ledger.Api.txInfoValidPeriod' field
    of 'Plutus.V1.Ledger.Api.TxInfo'.
 
    We avoid 'PPOSIXTimeRange' where we can in order to save on operations.
+
+   Note: 'PProposalTime' doesn't need a Haskell-level equivalent because it
+   is only used in scripts, and does not go in datums. It is also scott-encoded
+   which is more efficient in usage.
 -}
 data PProposalTime (s :: S) = PProposalTime
   { lowerBound :: Term s PPOSIXTime

agora/Agora/Utils.hs

@@ -687,5 +687,6 @@ mustBePDJust = phoistAcyclic $
     PDJust ((pfield @"_0" #) -> v) -> v
     _ -> ptraceError emsg
 
+-- | Create an 'Address' from a given 'ValidatorHash' with no 'Plutus.V1.Ledger.Credential.StakingCredential'.
 validatorHashToAddress :: ValidatorHash -> Address
 validatorHashToAddress vh = Address (ScriptCredential vh) Nothing