Document GADT constructor arguments

cardano-api/internal/Cardano/Api/Address.hs

@@ -688,6 +688,7 @@ fromShelleyAddrIsSbe sbe = \case
 
 fromShelleyAddr
   :: ShelleyBasedEra era
+  -- ^ Witness that the era is shelley era onwards
   -> Shelley.Addr StandardCrypto
   -> AddressInEra era
 fromShelleyAddr _ (Shelley.AddrBootstrap (Shelley.BootstrapAddress addr)) =

cardano-api/internal/Cardano/Api/Block.hs

@@ -183,7 +183,9 @@ getShelleyBlockTxs era (Ledger.Block _header txs) =
 data BlockInMode where
   BlockInMode
     :: CardanoEra era
+    -- ^ The era of the block
     -> Block era
+    -- ^ The block itself
     -> BlockInMode
 
 deriving instance Show BlockInMode

cardano-api/internal/Cardano/Api/Certificate.hs

@@ -247,12 +247,17 @@ data DRepMetadataReference
 data StakeAddressRequirements era where
   StakeAddrRegistrationConway
     :: ConwayEraOnwards era
+    -- ^ Witness that the era is conway onwards
     -> L.Coin
+    -- ^ Deposit
     -> StakeCredential
+    -- ^ Stake credential
     -> StakeAddressRequirements era
   StakeAddrRegistrationPreConway
     :: ShelleyToBabbageEra era
+    -- ^ Witness that the era is shelley to babbage
     -> StakeCredential
+    -- ^ Stake credential
     -> StakeAddressRequirements era
 
 makeStakeAddressRegistrationCertificate :: StakeAddressRequirements era -> Certificate era
@@ -283,13 +288,19 @@ makeStakeAddressUnregistrationCertificate req =
 data StakeDelegationRequirements era where
   StakeDelegationRequirementsConwayOnwards
     :: ConwayEraOnwards era
+    -- ^ Witness that the era is conway onwards
     -> StakeCredential
+    -- ^ Stake credential
     -> Ledger.Delegatee (EraCrypto (ShelleyLedgerEra era))
+    -- ^ Delegatee
     -> StakeDelegationRequirements era
   StakeDelegationRequirementsPreConway
     :: ShelleyToBabbageEra era
+    -- ^ Witness that the era is shelley to babbage
     -> StakeCredential
+    -- ^ Stake credential
     -> PoolId
+    -- ^ Pool id
     -> StakeDelegationRequirements era
 
 makeStakeAddressDelegationCertificate :: StakeDelegationRequirements era -> Certificate era
@@ -306,11 +317,15 @@ makeStakeAddressDelegationCertificate = \case
 data StakePoolRegistrationRequirements era where
   StakePoolRegistrationRequirementsConwayOnwards
     :: ConwayEraOnwards era
+    -- ^ Witness that the era is conway onwards
     -> Ledger.PoolParams (EraCrypto (ShelleyLedgerEra era))
+    -- ^ Pool parameters
     -> StakePoolRegistrationRequirements era
   StakePoolRegistrationRequirementsPreConway
     :: ShelleyToBabbageEra era
+    -- ^ Witness that the era is shelley to babbage
     -> Ledger.PoolParams (EraCrypto (ShelleyLedgerEra era))
+    -- ^ Pool parameters
     -> StakePoolRegistrationRequirements era
 
 makeStakePoolRegistrationCertificate
@@ -330,13 +345,19 @@ makeStakePoolRegistrationCertificate = \case
 data StakePoolRetirementRequirements era where
   StakePoolRetirementRequirementsConwayOnwards
     :: ConwayEraOnwards era
+    -- ^ Witness that the era is conway onwards
     -> PoolId
+    -- ^ Pool id
     -> Ledger.EpochNo
+    -- ^ Retirement epoch number
     -> StakePoolRetirementRequirements era
   StakePoolRetirementRequirementsPreConway
     :: ShelleyToBabbageEra era
+    -- ^ Witness that the era is shelley to babbage
     -> PoolId
+    -- ^ Pool id
     -> Ledger.EpochNo
+    -- ^ Retirement epoch number
     -> StakePoolRetirementRequirements era
 
 makeStakePoolRetirementCertificate
@@ -357,9 +378,13 @@ makeStakePoolRetirementCertificate req =
 data GenesisKeyDelegationRequirements ere where
   GenesisKeyDelegationRequirements
     :: ShelleyToBabbageEra era
+    -- ^ Witness that the era is shelley to babbage
     -> Hash GenesisKey
+    -- ^ Genesis key hash
     -> Hash GenesisDelegateKey
+    -- ^ Genesis delegate key hash
     -> Hash VrfKey
+    -- ^ VRF key hash
     -> GenesisKeyDelegationRequirements era
 
 makeGenesisKeyDelegationCertificate :: GenesisKeyDelegationRequirements era -> Certificate era
@@ -378,8 +403,11 @@ makeGenesisKeyDelegationCertificate
 data MirCertificateRequirements era where
   MirCertificateRequirements
     :: ShelleyToBabbageEra era
+    -- ^ Witness that the era is shelley to babbage
     -> Ledger.MIRPot
+    -- ^ MIR pot
     -> Ledger.MIRTarget (EraCrypto (ShelleyLedgerEra era))
+    -- ^ MIR target
     -> MirCertificateRequirements era
 
 makeMIRCertificate
@@ -394,8 +422,11 @@ makeMIRCertificate (MirCertificateRequirements atMostEra mirPot mirTarget) =
 data DRepRegistrationRequirements era where
   DRepRegistrationRequirements
     :: ConwayEraOnwards era
+    -- ^ Witness that the era is conway onwards
     -> (Ledger.Credential Ledger.DRepRole (EraCrypto (ShelleyLedgerEra era)))
+    -- ^ DRep credential
     -> L.Coin
+    -- ^ Deposit
     -> DRepRegistrationRequirements era
 
 makeDrepRegistrationCertificate
@@ -411,8 +442,11 @@ makeDrepRegistrationCertificate (DRepRegistrationRequirements conwayOnwards vcre
 data CommitteeHotKeyAuthorizationRequirements era where
   CommitteeHotKeyAuthorizationRequirements
     :: ConwayEraOnwards era
+    -- ^ Witness that the era is conway onwards
     -> Ledger.Credential Ledger.ColdCommitteeRole (EraCrypto (ShelleyLedgerEra era))
+    -- ^ Cold key credential
     -> Ledger.Credential Ledger.HotCommitteeRole (EraCrypto (ShelleyLedgerEra era))
+    -- ^ Hot key credential
     -> CommitteeHotKeyAuthorizationRequirements era
 
 makeCommitteeHotKeyAuthorizationCertificate
@@ -427,8 +461,11 @@ makeCommitteeHotKeyAuthorizationCertificate (CommitteeHotKeyAuthorizationRequire
 data CommitteeColdkeyResignationRequirements era where
   CommitteeColdkeyResignationRequirements
     :: ConwayEraOnwards era
+    -- ^ Witness that the era is conway onwards
     -> Ledger.Credential Ledger.ColdCommitteeRole (EraCrypto (ShelleyLedgerEra era))
+    -- ^ Cold key credential
     -> Maybe (Ledger.Anchor (EraCrypto (ShelleyLedgerEra era)))
+    -- ^ Anchor
     -> CommitteeColdkeyResignationRequirements era
 
 makeCommitteeColdkeyResignationCertificate
@@ -445,8 +482,11 @@ makeCommitteeColdkeyResignationCertificate (CommitteeColdkeyResignationRequireme
 data DRepUnregistrationRequirements era where
   DRepUnregistrationRequirements
     :: ConwayEraOnwards era
+    -- ^ Witness that the era is conway onwards
     -> (Ledger.Credential Ledger.DRepRole (EraCrypto (ShelleyLedgerEra era)))
+    -- ^ DRep credential
     -> L.Coin
+    -- ^ Deposit
     -> DRepUnregistrationRequirements era
 
 makeDrepUnregistrationCertificate
@@ -473,7 +513,9 @@ makeStakeAddressAndDRepDelegationCertificate w cred delegatee deposit =
 data DRepUpdateRequirements era where
   DRepUpdateRequirements
     :: ConwayEraOnwards era
+    -- ^ Witness that the era is conway onwards
     -> Ledger.Credential Ledger.DRepRole (EraCrypto (ShelleyLedgerEra era))
+    -- ^ DRep credential
     -> DRepUpdateRequirements era
 
 makeDrepUpdateCertificate
@@ -491,6 +533,7 @@ makeDrepUpdateCertificate (DRepUpdateRequirements conwayOnwards vcred) mAnchor =
 
 getTxCertWitness
   :: ShelleyBasedEra era
+  -- ^ Witness that the era is shelley era onwards
   -> Ledger.TxCert (ShelleyLedgerEra era)
   -> Maybe StakeCredential
 getTxCertWitness sbe ledgerCert = shelleyBasedEraConstraints sbe $

cardano-api/internal/Cardano/Api/Error.hs

@@ -37,7 +37,11 @@ throwErrorAsException :: Error e => e -> IO a
 throwErrorAsException e = throwIO (ErrorAsException e)
 
 data ErrorAsException where
-  ErrorAsException :: Error e => e -> ErrorAsException
+  ErrorAsException
+    :: Error e
+    => e
+    -- ^ The error
+    -> ErrorAsException
 
 instance Error ErrorAsException where
   prettyError (ErrorAsException e) =

cardano-api/internal/Cardano/Api/Fees.hs

@@ -505,6 +505,7 @@ data ResolvablePointers where
             , Ledger.ScriptHash Ledger.StandardCrypto
             )
         )
+    -- ^ A mapping of pointers that are possible to resolve
     -> ResolvablePointers
 
 deriving instance Show ResolvablePointers

cardano-api/internal/Cardano/Api/InMode.hs

@@ -64,7 +64,9 @@ data TxInMode where
   -- | Shelley based transactions.
   TxInMode
     :: ShelleyBasedEra era
+    -- ^ Witness that the era is shelley era onwards
     -> Tx era
+    -- ^ The transaction itself
     -> TxInMode
   -- | Legacy Byron transactions and things we can
   -- post to the chain which are not actually transactions.
@@ -148,7 +150,9 @@ toConsensusGenTx (TxInMode ShelleyBasedEraConway (ShelleyTx _ tx)) =
 data TxIdInMode where
   TxIdInMode
     :: CardanoEra era
+    -- ^ The cardano era
     -> TxId
+    -- ^ The transaction id
     -> TxIdInMode
 
 toConsensusTxId
@@ -204,10 +208,13 @@ toConsensusTxId (TxIdInMode ConwayEra txid) =
 data TxValidationError era where
   ByronTxValidationError
     :: Consensus.ApplyTxErr Consensus.ByronBlock
+    -- ^ The error from trying to submit a Byron transaction
     -> TxValidationError era
   ShelleyTxValidationError
     :: ShelleyBasedEra era
+    -- ^ Witness that the era is shelley era onwards
     -> Consensus.ApplyTxErr (Consensus.ShelleyBlock (ConsensusProtocol era) (ShelleyLedgerEra era))
+    -- ^ The error from trying to submit a Shelley transaction
     -> TxValidationError era
 
 deriving instance Generic (TxValidationError era)
@@ -260,10 +267,12 @@ data TxValidationErrorInCardanoMode where
   TxValidationErrorInCardanoMode
     :: ()
     => TxValidationError era
+    -- ^ The transaction validation error
     -> TxValidationErrorInCardanoMode
   TxValidationEraMismatch
     :: ()
     => EraMismatch
+    -- ^ The error from trying to submit a transaction to the wrong era
     -> TxValidationErrorInCardanoMode
 
 deriving instance Show TxValidationErrorInCardanoMode

cardano-api/internal/Cardano/Api/Modes.hs

@@ -63,6 +63,7 @@ import           Data.SOP.Strict (NS (S, Z))
 data ConsensusModeParams where
   CardanoModeParams
     :: Byron.EpochSlots
+    -- ^ The number of slots in an epoch.
     -> ConsensusModeParams
 
 deriving instance Show ConsensusModeParams

cardano-api/internal/Cardano/Api/ProtocolParameters.hs

@@ -203,39 +203,63 @@ createPParams sbe ebPParamsUpdate =
 data EraBasedProtocolParametersUpdate era where
   ShelleyEraBasedProtocolParametersUpdate
     :: CommonProtocolParametersUpdate
+    -- ^ Common protocol parameters
     -> DeprecatedAfterMaryPParams ShelleyEra
+    -- ^ Protocol parameters that have been deprecated after Mary
     -> DeprecatedAfterBabbagePParams ShelleyEra
+    -- ^ Protocol parameters that have been deprecated after Babbage
     -> ShelleyToAlonzoPParams ShelleyEra
+    -- ^ Protocol parameters that have been deprecated after Alonzo
     -> EraBasedProtocolParametersUpdate ShelleyEra
   AllegraEraBasedProtocolParametersUpdate
     :: CommonProtocolParametersUpdate
+    -- ^ Common protocol parameters
     -> DeprecatedAfterMaryPParams AllegraEra
+    -- ^ Protocol parameters that have been deprecated after Mary
     -> ShelleyToAlonzoPParams AllegraEra
+    -- ^ Protocol parameters that have been deprecated after Alonzo
     -> DeprecatedAfterBabbagePParams ShelleyEra
+    -- ^ Protocol parameters that have been deprecated after Babbage
     -> EraBasedProtocolParametersUpdate AllegraEra
   MaryEraBasedProtocolParametersUpdate
     :: CommonProtocolParametersUpdate
+    -- ^ Common protocol parameters
     -> DeprecatedAfterMaryPParams MaryEra
+    -- ^ Protocol parameters that have been deprecated after Mary
     -> ShelleyToAlonzoPParams MaryEra
+    -- ^ Protocol parameters that have been deprecated after Alonzo
     -> DeprecatedAfterBabbagePParams ShelleyEra
+    -- ^ Protocol parameters that have been deprecated after Babbage
     -> EraBasedProtocolParametersUpdate MaryEra
   AlonzoEraBasedProtocolParametersUpdate
     :: CommonProtocolParametersUpdate
+    -- ^ Common protocol parameters
     -> ShelleyToAlonzoPParams AlonzoEra
+    -- ^ Protocol parameters that have been deprecated after Alonzo
     -> AlonzoOnwardsPParams AlonzoEra
+    -- ^ Protocol parameters that have been introduced in Alonzo
     -> DeprecatedAfterBabbagePParams ShelleyEra
+    -- ^ Protocol parameters that have been deprecated after Babbage
     -> EraBasedProtocolParametersUpdate AlonzoEra
   BabbageEraBasedProtocolParametersUpdate
     :: CommonProtocolParametersUpdate
+    -- ^ Common protocol parameters
     -> AlonzoOnwardsPParams BabbageEra
+    -- ^ Protocol parameters that have been introduced in Babbage
     -> DeprecatedAfterBabbagePParams ShelleyEra
+    -- ^ Protocol parameters that have been deprecated after Babbage
     -> IntroducedInBabbagePParams BabbageEra
+    -- ^ Protocol parameters that have been introduced in Babbage
     -> EraBasedProtocolParametersUpdate BabbageEra
   ConwayEraBasedProtocolParametersUpdate
     :: CommonProtocolParametersUpdate
+    -- ^ Common protocol parameters
     -> AlonzoOnwardsPParams ConwayEra
+    -- ^ Protocol parameters that have been introduced in Conway
     -> IntroducedInBabbagePParams ConwayEra
+    -- ^ Protocol parameters that have been introduced in Babbage
     -> IntroducedInConwayPParams (ShelleyLedgerEra ConwayEra)
+    -- ^ Protocol parameters that have been introduced in Conway
     -> EraBasedProtocolParametersUpdate ConwayEra
 
 deriving instance Show (EraBasedProtocolParametersUpdate era)

cardano-api/internal/Cardano/Api/Query.hs

@@ -143,6 +143,7 @@ data QueryInMode result where
     :: QueryInMode AnyCardanoEra
   QueryInEra
     :: QueryInEra era result
+    -- ^ Query in a specific era
     -> QueryInMode (Either EraMismatch result)
   QueryEraHistory
     :: QueryInMode EraHistory
@@ -166,6 +167,7 @@ data EraHistory where
   EraHistory
     :: Consensus.CardanoBlock L.StandardCrypto ~ Consensus.HardForkBlock xs
     => History.Interpreter xs
+    -- ^ The history interpreter for the hard fork combinator
     -> EraHistory
 
 getProgress
@@ -239,15 +241,19 @@ data QueryInShelleyBasedEra era result where
     :: QueryInShelleyBasedEra era (Map (Hash StakePoolKey) Rational)
   QueryUTxO
     :: QueryUTxOFilter
+    -- ^ Filter the UTxO by this filter
     -> QueryInShelleyBasedEra era (UTxO era)
   QueryStakeAddresses
     :: Set StakeCredential
+    -- ^ Stake addresses to query
     -> NetworkId
+    -- ^ Network ID
     -> QueryInShelleyBasedEra era (Map StakeAddress L.Coin, Map StakeAddress PoolId)
   QueryStakePools
     :: QueryInShelleyBasedEra era (Set PoolId)
   QueryStakePoolParameters
     :: Set PoolId
+    -- ^ Stake pools to query
     -> QueryInShelleyBasedEra era (Map PoolId StakePoolParameters)
   -- TODO: add support for RewardProvenance
   -- QueryPoolRanking
@@ -261,15 +267,19 @@ data QueryInShelleyBasedEra era result where
     :: QueryInShelleyBasedEra era (SerialisedCurrentEpochState era)
   QueryPoolState
     :: Maybe (Set PoolId)
+    -- ^ Stake pools to query
     -> QueryInShelleyBasedEra era (SerialisedPoolState era)
   QueryPoolDistribution
     :: Maybe (Set PoolId)
+    -- ^ Stake pools to query
     -> QueryInShelleyBasedEra era (SerialisedPoolDistribution era)
   QueryStakeSnapshot
     :: Maybe (Set PoolId)
+    -- ^ Stake pools to query
     -> QueryInShelleyBasedEra era (SerialisedStakeSnapshots era)
   QueryStakeDelegDeposits
     :: Set StakeCredential
+    -- ^ Stake addresses to query
     -> QueryInShelleyBasedEra era (Map StakeCredential L.Coin)
   QueryAccountState
     :: QueryInShelleyBasedEra era L.AccountState

cardano-api/internal/Cardano/Api/SerialiseLedgerCddl.hs

@@ -278,11 +278,13 @@ data FromSomeTypeCDDL c b where
     :: Text
     -- ^ CDDL type that we want
     -> (InAnyShelleyBasedEra Tx -> b)
+    -- ^ Function to convert the tx to the desired type
     -> FromSomeTypeCDDL TextEnvelope b
   FromCDDLWitness
     :: Text
     -- ^ CDDL type that we want
     -> (InAnyShelleyBasedEra KeyWitness -> b)
+    -- ^ Function to convert the witness to the desired type
     -> FromSomeTypeCDDL TextEnvelope b
 
 deserialiseFromTextEnvelopeCddlAnyOf