add and fix haddock doc comments

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