io-sim-por: added haddocks & notes

Author: coot

io-sim/src/Control/Monad/IOSim/Types.hs

@@ -745,8 +745,17 @@ data StmStack s b a where
 ---
 
 data ScheduleControl = ControlDefault
+                     -- ^ default scheduling mode
                      | ControlAwait [ScheduleMod]
+                     -- ^ if the current control is 'ControlAwait', the normal
+                     -- scheduling will proceed, until the thread found in the
+                     -- first 'ScheduleMod' reaches the given step.  At this
+                     -- point the thread is put to sleep, until after all the
+                     -- steps are followed.
                      | ControlFollow [StepId] [ScheduleMod]
+                     -- ^ follow the steps then continue with schedule
+                     -- modifications.  This control is set by 'followControl'
+                     -- when 'controlTargets' returns true.
   deriving (Eq, Ord, Show)
 
 data ScheduleMod = ScheduleMod{

io-sim/src/Control/Monad/IOSimPOR/Internal.hs

@@ -1577,7 +1577,11 @@ extendScheduleControl' (ControlAwait mods) m =
       if isUndo
         then ControlAwait mods          -- reject this mod... it's undoing a previous one
         else ControlAwait (take common mods++[m''])
-extendScheduleControl' ControlFollow{} ScheduleMod{} = error "Impossible: extendScheduleControl' ControlFollow{} ScheduleMod{}"
+extendScheduleControl' ControlFollow{} ScheduleMod{} =
+  -- note: this case is impossible, since `extendScheduleControl'` first
+  -- argument is either the initial `ControlDefault` or a result of calling
+  -- `extendScheduleControl'` itself.
+  error "Impossible: extendScheduleControl' ControlFollow{} ScheduleMod{}"
 
 extendScheduleControl :: ScheduleControl -> ScheduleMod -> ScheduleControl
 extendScheduleControl control m =