diff --git a/io-sim/src/Control/Monad/IOSimPOR/Internal.hs b/io-sim/src/Control/Monad/IOSimPOR/Internal.hs
index 72409a6b..970fda51 100644
--- a/io-sim/src/Control/Monad/IOSimPOR/Internal.hs
+++ b/io-sim/src/Control/Monad/IOSimPOR/Internal.hs
@@ -826,6 +826,21 @@ threadInterruptible thread =
         | otherwise              -> False
       MaskedUninterruptible      -> False
 
+
+-- | Deschedule a thread.
+--
+-- A thread is descheduled, which marks a boundary of a `Step` when:
+--
+-- * forking a new thread
+-- * thread termination
+-- * setting the masking state to interruptible
+-- * popping masking frame (which resets masking state)
+-- * starting or cancelling a timeout
+-- * thread delays
+-- * on committed or blocked, but not aborted STM transactions
+-- * on blocking or non-blocking `throwTo`
+-- * unhandled exception in a (non-main) thread
+--
 deschedule :: Deschedule -> Thread s a -> SimState s a -> ST s (SimTrace a)
 
 deschedule Yield thread@Thread { threadId     = tid,
diff --git a/io-sim/src/Control/Monad/IOSimPOR/Types.hs b/io-sim/src/Control/Monad/IOSimPOR/Types.hs
index 772acb51..af5a82c8 100644
--- a/io-sim/src/Control/Monad/IOSimPOR/Types.hs
+++ b/io-sim/src/Control/Monad/IOSimPOR/Types.hs
@@ -176,6 +176,9 @@ instance Show ScheduleMod where
 -- Steps
 --
 
+-- | A unit of execution.  `deschedule` marks a boundary of a `Step`, see it's
+-- haddocks.
+--
 data Step = Step {
     stepThreadId :: !IOSimThreadId,
     stepStep     :: !Int,