io-sim: improved haddocks

coot · coot · commit 19f22cec7e7b · 2024-01-02T11:41:35.000+01:00
diff --git a/io-sim/src/Control/Monad/IOSim.hs b/io-sim/src/Control/Monad/IOSim.hs
@@ -133,6 +133,9 @@ import           System.IO.Unsafe
 import qualified Debug.Trace as Debug
 
 
+-- | Select events according to the predicate function.  It throws an error if
+-- the simulation ends with 'Failure'.
+--
 selectTraceEvents
     :: (Time -> SimEventType -> Maybe b)
     -> SimTrace a
@@ -150,6 +153,9 @@ selectTraceEvents fn =
               []
     . traceSelectTraceEvents fn
 
+-- | Like 'selectTraceEvents', but it returns even if the simulation trace ends
+-- with 'Failure'.
+--
 selectTraceEvents'
     :: (Time ->  SimEventType -> Maybe b)
     -> SimTrace a
@@ -216,10 +222,10 @@ detachTraceRaces = Trace.filter (\a -> case a of
                                          SimRacesFound {} -> False
                                          _                -> True)
 
--- | Select all the traced values matching the expected type. This relies on
--- the sim's dynamic trace facility.
+-- | Select all the traced values matching the expected type.  It relies on the
+-- sim's dynamic trace facility.
 --
--- For convenience, this throws exceptions for abnormal sim termination.
+-- For convenience, it throws exceptions for abnormal sim termination.
 --
 selectTraceEventsDynamic :: forall a b. Typeable b => SimTrace a -> [b]
 selectTraceEventsDynamic = selectTraceEvents fn
@@ -228,7 +234,8 @@ selectTraceEventsDynamic = selectTraceEvents fn
     fn _ (EventLog dyn) = fromDynamic dyn
     fn _ _              = Nothing
 
--- | Like 'selectTraceEventsDynamic' but also captures time of the trace event.
+-- | Like 'selectTraceEventsDynamic' but it also captures time of the trace
+-- event.
 --
 selectTraceEventsDynamicWithTime :: forall a b. Typeable b => SimTrace a -> [(Time, b)]
 selectTraceEventsDynamicWithTime = selectTraceEvents fn
@@ -237,8 +244,8 @@ selectTraceEventsDynamicWithTime = selectTraceEvents fn
     fn t (EventLog dyn) = (t,) <$> fromDynamic dyn
     fn _ _              = Nothing
 
--- | Like 'selectTraceEventsDynamic' but returns partial trace if an exception
--- is found in it.
+-- | Like 'selectTraceEventsDynamic' but it returns even if the simulation trace
+-- ends with 'Failure'.
 --
 selectTraceEventsDynamic' :: forall a b. Typeable b => SimTrace a -> [b]
 selectTraceEventsDynamic' = selectTraceEvents' fn
@@ -247,7 +254,8 @@ selectTraceEventsDynamic' = selectTraceEvents' fn
     fn _ (EventLog dyn) = fromDynamic dyn
     fn _ _              = Nothing
 
--- | Like `selectTraceEventsDynamic'` but also captures time of the trace event.
+-- | Like `selectTraceEventsDynamic'` but it also captures time of the trace
+-- event.
 --
 selectTraceEventsDynamicWithTime' :: forall a b. Typeable b => SimTrace a -> [(Time, b)]
 selectTraceEventsDynamicWithTime' = selectTraceEvents' fn
@@ -258,7 +266,7 @@ selectTraceEventsDynamicWithTime' = selectTraceEvents' fn
 
 -- | Get a trace of 'EventSay'.
 --
--- For convenience, this throws exceptions for abnormal sim termination.
+-- For convenience, it throws exceptions for abnormal sim termination.
 --
 selectTraceEventsSay :: SimTrace a -> [String]
 selectTraceEventsSay = selectTraceEvents fn
@@ -267,7 +275,7 @@ selectTraceEventsSay = selectTraceEvents fn
     fn _ (EventSay s) = Just s
     fn _ _            = Nothing
 
--- | Like 'selectTraceEventsSay' but also captures time of the trace event.
+-- | Like 'selectTraceEventsSay' but it also captures time of the trace event.
 --
 selectTraceEventsSayWithTime :: SimTrace a -> [(Time, String)]
 selectTraceEventsSayWithTime = selectTraceEvents fn
@@ -276,8 +284,8 @@ selectTraceEventsSayWithTime = selectTraceEvents fn
     fn t (EventSay s) = Just (t, s)
     fn _ _            = Nothing
 
--- | Like 'selectTraceEventsSay' but return partial trace if an exception is
--- found in it.
+-- | Like 'selectTraceEventsSay' but it returns even if the simulation trace
+-- ends with 'Failure'.
 --
 selectTraceEventsSay' :: SimTrace a -> [String]
 selectTraceEventsSay' = selectTraceEvents' fn
@@ -286,7 +294,7 @@ selectTraceEventsSay' = selectTraceEvents' fn
     fn _ (EventSay s) = Just s
     fn _ _            = Nothing
 
--- | Like `selectTraceEventsSay'` but also captures time of the trace event.
+-- | Like `selectTraceEventsSay'` but it also captures time of the trace event.
 --
 selectTraceEventsSayWithTime' :: SimTrace a -> [(Time, String)]
 selectTraceEventsSayWithTime' = selectTraceEvents' fn
@@ -297,13 +305,13 @@ selectTraceEventsSayWithTime' = selectTraceEvents' fn
 
 -- | Print all 'EventSay' to the console.
 --
--- For convenience, this throws exceptions for abnormal sim termination.
+-- For convenience, it throws exceptions for abnormal sim termination.
 --
 printTraceEventsSay :: SimTrace a -> IO ()
 printTraceEventsSay = mapM_ print . selectTraceEventsSay
 
 
--- | The most general select function.  It is a _total_ function.
+-- | The most general select function.  It is a /total function/.
 --
 traceSelectTraceEvents
     :: (Time -> SimEventType -> Maybe b)
@@ -324,7 +332,7 @@ traceSelectTraceEvents fn = bifoldr ( \ v _acc -> Nil v )
                                     )
                                     undefined -- it is ignored
 
--- | Select dynamic events.  It is a _total_ function.
+-- | Select dynamic events.  It is a /total function/.
 --
 traceSelectTraceEventsDynamic :: forall a b. Typeable b
                               => SimTrace a -> Trace (SimResult a) b
@@ -335,7 +343,7 @@ traceSelectTraceEventsDynamic = traceSelectTraceEvents fn
     fn _ _              = Nothing
 
 
--- | Select say events.  It is a _total_ function.
+-- | Select say events.  It is a /total function/.
 --
 traceSelectTraceEventsSay :: forall a.  SimTrace a -> Trace (SimResult a) String
 traceSelectTraceEventsSay = traceSelectTraceEvents fn
@@ -417,7 +425,7 @@ runSimOrThrow mainAction =
 runSimStrictShutdown :: forall a. (forall s. IOSim s a) -> Either Failure a
 runSimStrictShutdown mainAction = traceResult True (runSimTrace mainAction)
 
--- | Fold through the trace and return either a 'Failure' or the simulation
+-- | Fold through the trace and return either 'Failure' or a simulation
 -- result, i.e. the return value of the main thread.
 --
 traceResult :: Bool
@@ -502,19 +510,18 @@ runSimTrace mainAction = runST (runSimTraceST mainAction)
 -- slot.  In /IOSim/ and /IOSimPOR/ time only moves explicitly through timer
 -- events, e.g. things like `Control.Monad.Class.MonadTimer.SI.threadDelay`,
 -- `Control.Monad.Class.MonadTimer.SI.registerDelay` or the
--- `Control.Monad.Class.MonadTimer.NonStandard.MonadTimeout` API.  The usual
+-- `Control.Monad.Class.MonadTimer.MonadTimeout.NonStandard` API.  The usual
 -- QuickCheck techniques can help explore different schedules of
 -- threads too.
 
 -- | Execute a simulation, discover & revert races.  Note that this will execute
 -- the simulation multiple times with different schedules, and thus it's much
 -- more costly than a simple `runSimTrace` (also the simulation environments has
--- much more state to track and hence is slower).
+-- much more state to track and hence it is slower).
 --
 -- On property failure it will show the failing schedule (`ScheduleControl`)
--- which can be plugged to `controlSimTrace`.
---
--- Note: `exploreSimTrace` evaluates each schedule in parallel (using `par`).
+-- which can be passed to `controlSimTrace` to reproduce the failure without
+-- discovering the schedule.
 --
 exploreSimTrace
   :: forall a test. Testable test
@@ -533,8 +540,6 @@ exploreSimTrace optsf main k =
 -- | An 'ST' version of 'exploreSimTrace'. The callback also receives
 -- 'ScheduleControl'.  This is mostly useful for testing /IOSimPOR/ itself.
 --
--- Note: `exploreSimTraceST` evaluates each schedule sequentially.
---
 exploreSimTraceST
   :: forall s a test. Testable test
   => (ExplorationOptions -> ExplorationOptions)
@@ -689,15 +694,15 @@ raceReversals ControlDefault      = 0
 raceReversals (ControlAwait mods) = length mods
 raceReversals ControlFollow{}     = error "Impossible: raceReversals ControlFollow{}"
 
--- compareTraces is given (maybe) a passing trace and a failing trace,
+-- `compareTracesST` is given (maybe) a passing trace and a failing trace,
 -- and identifies the point at which they diverge, where it inserts a
 -- "sleep" event for the thread that is delayed in the failing case,
 -- and a "wake" event before its next action. It also returns the
 -- identity and time of the sleeping thread. Since we expect the trace
 -- to be consumed lazily (and perhaps only partially), and since the
 -- sleeping thread is not of interest unless the trace is consumed
 -- this far, then we collect its identity only if it is reached using
--- unsafePerformIO.
+-- `unsafePerformIO`.
 
 -- TODO: return StepId
 compareTracesST :: forall a b s.
diff --git a/io-sim/src/Control/Monad/IOSim/Internal.hs b/io-sim/src/Control/Monad/IOSim/Internal.hs
@@ -991,10 +991,10 @@ lookupThreadLabel :: IOSimThreadId -> Map IOSimThreadId (Thread s a) -> Maybe Th
 lookupThreadLabel tid threads = join (threadLabel <$> Map.lookup tid threads)
 
 
--- | The most general method of running 'IOSim' is in 'ST' monad.  One can
--- recover failures or the result from 'SimTrace' with
--- 'Control.Monad.IOSim.traceResult', or access 'SimEventType's generated by the
--- computation with 'Control.Monad.IOSim.traceEvents'.  A slightly more
+-- | The most general method of running 'IOSim' is in the lazy 'ST' monad.  One
+-- can recover failures or the result from 'SimTrace' with
+-- 'Control.Monad.IOSim.traceResult', or access 'SimEventType's generated by
+-- the computation with 'Control.Monad.IOSim.traceEvents'.  A slightly more
 -- convenient way is exposed by 'Control.Monad.IOSim.runSimTrace'.
 --
 runSimTraceST :: forall s a. IOSim s a -> ST s (SimTrace a)
diff --git a/io-sim/src/Control/Monad/IOSim/Types.hs b/io-sim/src/Control/Monad/IOSim/Types.hs
@@ -143,7 +143,7 @@ newtype IOSim s a = IOSim { unIOSim :: forall r. (a -> SimA s r) -> SimA s r }
 runIOSim :: IOSim s a -> SimA s a
 runIOSim (IOSim k) = k Return
 
--- | 'IOSim' has the ability to story any 'Typeable' value in its trace which
+-- | 'IOSim' has the ability to store any 'Typeable' value in its trace which
 -- can then be recovered with `selectTraceEventsDynamic` or
 -- `selectTraceEventsDynamic'`.
 --
@@ -234,7 +234,9 @@ data StmA s a where
   LiftSTStm    :: StrictST.ST s a -> (a -> StmA s b) -> StmA s b
   FixStm       :: (x -> STM s x) -> (x -> StmA s r) -> StmA s r
 
--- Exported type
+-- | `IOSim`'s 'MonadSTM.STM' monad, as 'IOSim' it is parametrised by @s@, e.g.
+-- @STMSim s a@ is monadic expression of type @a@.
+--
 type STMSim = STM
 
 --
@@ -630,8 +632,9 @@ instance MonadST (IOSim s) where
 
 -- | Lift an 'StrictST.ST' computation to 'IOSim'.
 --
--- Note: you can use 'MonadST' to lift 'StrictST.ST' computations, this is just
+-- Note: you can use 'MonadST' to lift 'StrictST.ST' computations, this is
 -- a more convenient function just for 'IOSim'.
+--
 liftST :: StrictST.ST s a -> IOSim s a
 liftST action = IOSim $ oneShot $ \k -> LiftST action k
 
@@ -816,14 +819,15 @@ data SimResult a
     -- ^ Return value of the main thread.
     | MainException !Time !(Labelled IOSimThreadId) SomeException ![Labelled IOSimThreadId]
     -- ^ Exception thrown by the main thread.
-    | Deadlock      !Time               ![Labelled IOSimThreadId]
+    | Deadlock      !Time ![Labelled IOSimThreadId]
     -- ^ Deadlock discovered in the simulation.  Deadlocks are discovered if
     -- simply the simulation cannot do any progress in a given time slot and
     -- there's no event which would advance the time.
     | Loop
     -- ^ Only returned by /IOSimPOR/ when a step execution took longer than
     -- 'explorationStepTimelimit` was exceeded.
     | InternalError String
+    -- ^ An `IOSim` bug, please report to <https://github.com/input-output-hk/io-sim>
     deriving (Show, Functor)
 
 ppSimResult :: Show a
@@ -874,6 +878,12 @@ type SimTrace a = Trace.Trace (SimResult a) SimEvent
 
 -- | Pretty print simulation trace.
 --
+-- Note: this is not a streaming function, it will evaluate the whole trace
+-- before printing it.  If you need to print a very large trace, you might want
+-- to use
+--
+-- @'Trace.ppTrace' show ('ppSimEvent' 0 0 0)@
+--
 ppTrace :: Show a => SimTrace a -> String
 ppTrace tr = Trace.ppTrace
                (ppSimResult timeWidth tidWidth labelWidth)
@@ -1083,6 +1093,8 @@ data SimEventType
   | EventPerformAction StepId
   -- ^ /IOSimPOR/ event: perform action of the given step
   | EventReschedule           ScheduleControl
+  -- ^ /IOSimPOR/ event: reschedule a thread following the given
+  -- `ScheduleControl`
 
   | EventEffect VectorClock Effect
   -- ^ /IOSimPOR/ event: executed effect; Useful for debugging IOSimPOR or
