Fix haddock comments (j-mueller#102)

* Fix haddock comment on convex-node-client

* Fix haddock comment on convex-coin-selection

* Fix haddock for convex-devnet

* Add doc generation on ci

* Fix un-ada haddock documentation

.github/workflows/ci-linux.yaml

@@ -109,4 +109,5 @@ jobs:
         run: |
           cabal build -j all
           cabal test all
+          cabal haddock -j all
 

cabal.project

@@ -104,6 +104,16 @@ source-repository-package
   location: https://github.com/j-mueller/csv
   tag: b2f00d7819ff62cb80532adfbc28dbc1046d3d96
 
+
+-- The plugin will typically fail when producing Haddock documentation. However,
+-- in this instance you can simply tell it to defer any errors to runtime (which
+-- will never happen since you're building documentation).
+--
+-- So, any package using 'PlutusTx.compile' in the code for which you need to
+-- generate haddock documentation should use the following 'haddock-options'.
+package un-ada
+    haddock-options: "--optghc=-fplugin-opt PlutusTx.Plugin:defer-errors"
+
 -- -------------------------------------------------------------------------
 -- Constraints tweaking
 

src/coin-selection/lib/Convex/CoinSelection.hs

@@ -519,10 +519,10 @@ any non-Ada asset it contains. If the positive part only contains Ada then no
 output is added.
 -}
 addOutputForNonAdaAssets ::
-  Core.PParams Ledger.Era.ERA -> -- ^ Protocol parameters (for computing the minimum lovelace amount in the output)
-  C.TxOut C.CtxTx C.BabbageEra -> -- ^ Address of the newly created output
-  C.Value -> -- ^ The balance of the transaction
-  (C.TxOut C.CtxTx C.BabbageEra, C.Lovelace) -- ^ The modified transaction body and the lovelace portion of the change output's value. If no output was added then the amount will be 0.
+  Core.PParams Ledger.Era.ERA -- ^ Protocol parameters (for computing the minimum lovelace amount in the output)
+  -> C.TxOut C.CtxTx C.BabbageEra -- ^ Address of the newly created output
+  -> C.Value -- ^ The balance of the transaction
+  -> (C.TxOut C.CtxTx C.BabbageEra, C.Lovelace) -- ^ The modified transaction body and the lovelace portion of the change output's value. If no output was added then the amount will be 0.
 addOutputForNonAdaAssets pparams returnUTxO (C.valueFromList . snd . splitValue -> positives)
   | isNothing (C.valueToLovelace positives) =
       let vlWithoutAda = positives & set (L._Value . at C.AdaAssetId) Nothing

src/coin-selection/lib/Convex/Query.hs

@@ -131,10 +131,12 @@ deriving newtype instance MonadError e m => MonadError e (WalletAPIQueryT m)
 -}
 balancePaymentCredentials ::
   (MonadBlockchain m, MonadUtxoQuery m, MonadError BalanceAndSubmitError m) =>
-  Tracer m TxBalancingMessage ->
-  C.PaymentCredential -> -- ^ Primary payment credential, used for return output
-  [C.PaymentCredential] -> -- ^ Other payment credentials, used for balancing
-  Maybe (C.TxOut C.CtxTx C.BabbageEra) -> C.TxBodyContent C.BuildTx C.BabbageEra -> m (C.Tx C.BabbageEra)
+  Tracer m TxBalancingMessage
+  -> C.PaymentCredential -- ^ Primary payment credential, used for return output
+  -> [C.PaymentCredential] -- ^ Other payment credentials, used for balancing
+  -> Maybe (C.TxOut C.CtxTx C.BabbageEra)
+  -> C.TxBodyContent C.BuildTx C.BabbageEra
+  -> m (C.Tx C.BabbageEra)
 balancePaymentCredentials dbg primaryCred otherCreds returnOutput txBody = do
   output <- maybe (returnOutputFor primaryCred) pure returnOutput
   (C.BalancedTxBody txbody _changeOutput _fee, _) <- liftEither BalanceError (balanceTx dbg (primaryCred:otherCreds) output txBody)

src/devnet/lib/Convex/Devnet/NodeQueries.hs

@@ -60,20 +60,20 @@ instance Exception QueryException
 
 -- | Get the 'SystemStart' from the node
 querySystemStart ::
-  NetworkId ->
-    -- ^ network Id to use for node query
-  FilePath ->
-    -- ^ Node socket
-  IO SystemStart
+  NetworkId
+  -- ^ network Id to use for node query
+  -> FilePath
+  -- ^ Node socket
+  -> IO SystemStart
 querySystemStart = queryLocalState C.QuerySystemStart
 
 -- | Get the 'EraHistory' from the node
 queryEraHistory ::
-  NetworkId ->
-    -- ^ network Id to use for node query
-  FilePath ->
-    -- ^ Node socket
-  IO (EraHistory CardanoMode)
+  NetworkId
+  -- ^ network Id to use for node query
+  -> FilePath
+  -- ^ Node socket
+  -> IO (EraHistory CardanoMode)
 queryEraHistory = queryLocalState (C.QueryEraHistory C.CardanoModeIsMultiEra)
 
 queryLocalState :: QueryInMode CardanoMode b -> NetworkId -> FilePath -> IO b
@@ -99,11 +99,11 @@ queryTipBlock = queryLocalState C.QueryChainBlockNo
 
 -- | Get the tip (slot no. and block hash) from the node
 queryTip ::
-  NetworkId ->
-    -- ^ network Id to use for node query
-  FilePath ->
-    -- ^ Node socket
-  IO (SlotNo, SlotLength, C.Hash C.BlockHeader)
+  NetworkId
+  -- ^ network Id to use for node query
+  -> FilePath
+  -- ^ Node socket
+  -> IO (SlotNo, SlotLength, C.Hash C.BlockHeader)
 queryTip networkId socket = queryLocalState (C.QueryChainPoint C.CardanoMode) networkId socket >>= \case
   C.ChainPointAtGenesis -> failure "queryTip: chain point at genesis"
   C.ChainPoint slot hsh -> getSlotLength slot >>= (\i -> pure (slot, i, hsh))
@@ -118,11 +118,11 @@ queryTip networkId socket = queryLocalState (C.QueryChainPoint C.CardanoMode) ne
 
 -- | Get the slot no of the current tip from the node
 queryTipSlotNo ::
-  NetworkId ->
-    -- ^ network Id to use for node query
-  FilePath ->
-    -- ^ Node socket
-  IO (SlotNo, SlotLength)
+  NetworkId
+  -- ^ network Id to use for node query
+  -> FilePath
+  -- ^ Node socket
+  -> IO (SlotNo, SlotLength)
 queryTipSlotNo networkId socket = queryTip networkId socket >>= (\(s, l, _) -> pure (s, l))
 
 -- | Query UTxO for all given addresses at given point.

src/node-client/lib/Convex/NodeClient/Fold.hs

@@ -127,15 +127,11 @@ foldClient initialState env applyBlock =
 foldClient' ::
   forall s w.
   Monoid w =>
-  -- | Initial state
-  s ->
-  -- | Node connection data
-  Env ->
-  -- | Rollback
-  (ChainPoint -> w -> s -> IO (w, s)) ->
-  -- | Fold
-  (CatchingUp -> s -> BlockInMode CardanoMode -> IO (Maybe (w, s))) -> -- ^ Fold
-  PipelinedLedgerStateClient
+  s -- ^ Initial state
+  -> Env -- ^ Node connection data
+  -> (ChainPoint -> w -> s -> IO (w, s)) -- ^ Rollback
+  -> (CatchingUp -> s -> BlockInMode CardanoMode -> IO (Maybe (w, s))) -- ^ Fold
+  -> PipelinedLedgerStateClient
 foldClient' initialState env applyRollback applyBlock = PipelinedLedgerStateClient $ CSP.ChainSyncClientPipelined $ do
 
 -- NB: The code below was adapted from https://input-output-hk.github.io/cardano-node/cardano-api/src/Cardano.Api.LedgerState.html#foldBlocks
@@ -221,20 +217,16 @@ foldClient' initialState env applyRollback applyBlock = PipelinedLedgerStateClie
 type History a = Seq (SlotNo, a)
 
 -- | Add a new state to the history
-pushHistoryState
-  :: -- | Environement used to get the security param, k.
-    Env
-     -- | History of k items.
-  -> History a
-     -- | Slot number of the new item.
-  -> SlotNo
-     -- | New item to add to the history
-  -> a
-  -- | ( The new history with the new item appended
+pushHistoryState ::
+  Env -- ^ Environement used to get the security param, k.
+  -> History a -- ^ History of k items.
+  -> SlotNo -- ^ Slot number of the new item.
+  -> a -- ^ New item to add to the history
+  -> (History a, History a)
+  -- ^ ( The new history with the new item appended
   --   , Any exisiting items that are now past the security parameter
   --      and hence can no longer be rolled back.
   --   )
-  -> (History a, History a)
 
 pushHistoryState env hist ix st
   = Seq.splitAt

src/node-client/lib/Convex/NodeClient/Types.hs

@@ -42,14 +42,10 @@ newtype PipelinedLedgerStateClient =
     }
 
 runNodeClient ::
-  -- | Path to the cardano-node config file (e.g. <path to cardano-node project>/configuration/cardano/mainnet-config.json)
-  FilePath
-  -- | Path to local cardano-node socket. This is the path specified by the @--socket-path@ command line option when running the node.
-  -> FilePath
-  -- | Client
-  -> (LocalNodeConnectInfo CardanoMode -> Env -> IO PipelinedLedgerStateClient)
-  -- | Final state
-  -> ExceptT InitialLedgerStateError IO ()
+  FilePath -- ^ Path to the cardano-node config file (e.g. <path to cardano-node project>/configuration/cardano/mainnet-config.json)
+  -> FilePath -- ^ Path to local cardano-node socket. This is the path specified by the @--socket-path@ command line option when running the node.
+  -> (LocalNodeConnectInfo CardanoMode -> Env -> IO PipelinedLedgerStateClient) -- ^ Client
+  -> ExceptT InitialLedgerStateError IO () -- ^ Final state
 runNodeClient nodeConfigFilePath socketPath client = do
   (connectInfo, env) <- loadConnectInfo nodeConfigFilePath socketPath
   c <- liftIO (client connectInfo env)

src/un-ada/lib/UnAda/OffChain/Transaction.hs

@@ -35,11 +35,11 @@ mintUnAda n currentTime q =
 
 addOutputFor ::
   MonadBuildTx m =>
-  NetworkId ->
-  POSIXTime ->
-    -- ^ Current time
-  Quantity ->
-  m ()
+  NetworkId
+  -> POSIXTime
+  -- ^ Current time
+  -> Quantity
+  -> m ()
 addOutputFor n spendAfter q =
   let vl = lovelaceToValue (quantityToLovelace q)
       dt = UnAdaState{spendAfter, mps = mintingPolicyHash}

src/un-ada/lib/UnAda/OnChain/Types.hs

@@ -9,25 +9,24 @@ module UnAda.OnChain.Types(
   UnAdaState(..),
   BuiltinData(
     UnAdaStateBuiltin,
-    -- * Script context
+    -- Script context
     ScriptContext,
     txInfo,
     purpose,
-    -- * Matching on tx info
+    -- Matching on tx info
     TxInfoV2,
     inputs,
     referenceInputs,
     outputs,
     fee,
     rest8,
-    -- * Validity intervals
+    -- Validity intervals
     FinitePOSIXTimeRange,
     fiFrom,
     fiTo,
     FiniteExtended,
     ItvlBound,
-
-    -- * UnAda context
+    -- UnAda context
     UnAdaContext,
     uacValueMinted,
     uacValidRange