Add haddocks for chain state history and update outdated ones

cardano-scaling · Sep 7, 2023 · caf99d3 · caf99d3
1 parent 67259d6
commit caf99d3
Show file tree

Hide file tree

Showing 2 changed files with 8 additions and 14 deletions.
diff --git a/hydra-node/src/Hydra/Chain.hs b/hydra-node/src/Hydra/Chain.hs
@@ -173,6 +173,9 @@ instance Arbitrary Lovelace where
 instance (IsTx tx, Arbitrary (ChainStateType tx)) => Arbitrary (PostTxError tx) where
   arbitrary = genericArbitrary
 
+-- | A non empty sequence of chain states that can be rolled back.
+-- This is expected to be constructed by using the smart constructor
+-- 'initHistory'.
 data ChainStateHistory tx = UnsafeChainStateHistory
   { history :: NonEmpty (ChainStateType tx)
   , defaultChainState :: ChainStateType tx
@@ -186,17 +189,9 @@ pushNewState :: ChainStateType tx -> ChainStateHistory tx -> ChainStateHistory t
 pushNewState cs h@UnsafeChainStateHistory{history} = h{history = cs <| history}
 
 initHistory :: ChainStateType tx -> ChainStateHistory tx
-initHistory cs =
-  UnsafeChainStateHistory
-    { history = cs :| []
-    , defaultChainState = cs
-    }
-
-rollbackHistory ::
-  IsChainState tx =>
-  ChainSlot ->
-  ChainStateHistory tx ->
-  ChainStateHistory tx
+initHistory cs = UnsafeChainStateHistory{history = cs :| [], defaultChainState = cs}
+
+rollbackHistory :: IsChainState tx => ChainSlot -> ChainStateHistory tx -> ChainStateHistory tx
 rollbackHistory rollbackChainSlot h@UnsafeChainStateHistory{history, defaultChainState} =
   h{history = fromMaybe (defaultChainState :| []) (nonEmpty rolledBack)}
  where

diff --git a/hydra-node/src/Hydra/Chain/Direct/Handlers.hs b/hydra-node/src/Hydra/Chain/Direct/Handlers.hs
@@ -69,16 +69,15 @@ import Hydra.Logging (Tracer, traceWith)
 import Hydra.Plutus.Orphans ()
 import System.IO.Error (userError)
 
--- | Handle of a local chain state that is kept in the direct chain layer.
+-- | Handle of a mutable local chain state that is kept in the direct chain layer.
 data LocalChainState m tx = LocalChainState
   { getLatest :: STM m (ChainStateType tx)
   , pushNew :: ChainStateType tx -> STM m ()
   , rollback :: ChainSlot -> STM m (ChainStateType tx)
   , history :: STM m (ChainStateHistory tx)
   }
 
--- | Initialize a new local chain state with given 'ChainStateAt' (see also
--- 'initialChainState').
+-- | Initialize a new local chain state from a given chain state history.
 newLocalChainState ::
   (MonadSTM m, IsChainState tx) =>
   ChainStateHistory tx ->