From caf99d38e6513fcb3fba79b1bb9697411e7f7104 Mon Sep 17 00:00:00 2001
From: Franco Testagrossa <franco.testagrossa@gmail.com>
Date: Thu, 7 Sep 2023 11:23:21 +0200
Subject: [PATCH] Add haddocks for chain state history and update outdated ones

---
 hydra-node/src/Hydra/Chain.hs                 | 17 ++++++-----------
 hydra-node/src/Hydra/Chain/Direct/Handlers.hs |  5 ++---
 2 files changed, 8 insertions(+), 14 deletions(-)

diff --git a/hydra-node/src/Hydra/Chain.hs b/hydra-node/src/Hydra/Chain.hs
index 3e63dab2b47..84fb023fb7b 100644
--- 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
index 5e3885811d4..0a34410c563 100644
--- a/hydra-node/src/Hydra/Chain/Direct/Handlers.hs
+++ b/hydra-node/src/Hydra/Chain/Direct/Handlers.hs
@@ -69,7 +69,7 @@ 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 ()
@@ -77,8 +77,7 @@ data LocalChainState m tx = LocalChainState
   , 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 ->