Update the Exception docs

[ghc-base.git] / GHC / IOBase.lhs

diff --git a/GHC/IOBase.lhs b/GHC/IOBase.lhs
index 48a0950..a952bd5 100644 (file)
--- a/GHC/IOBase.lhs
+++ b/GHC/IOBase.lhs
@@ -634,6 +634,8 @@ showHandle file = showString "{handle: " . showString file . showString "}"
 -- ------------------------------------------------------------------------
 -- Exception datatypes and operations
 
+-- |The thread is blocked on an @MVar@, but there are no other references
+-- to the @MVar@ so it can't ever continue.
 data BlockedOnDeadMVar = BlockedOnDeadMVar
     deriving Typeable
 
@@ -647,6 +649,8 @@ blockedOnDeadMVar = toException BlockedOnDeadMVar
 
 -----
 
+-- |The thread is awiting to retry an STM transaction, but there are no
+-- other references to any @TVar@s involved, so it can't ever continue.
 data BlockedIndefinitely = BlockedIndefinitely
     deriving Typeable
 
@@ -660,6 +664,8 @@ blockedIndefinitely = toException BlockedIndefinitely
 
 -----
 
+-- |There are no runnable threads, so the program is deadlocked.
+-- The @Deadlock@ exception is raised in the main thread only.
 data Deadlock = Deadlock
     deriving Typeable
 
@@ -670,6 +676,8 @@ instance Show Deadlock where
 
 -----
 
+-- |Exceptions generated by 'assert'. The @String@ gives information
+-- about the source location of the assertion.
 data AssertionFailed = AssertionFailed String
     deriving Typeable
 
@@ -680,7 +688,7 @@ instance Show AssertionFailed where
 
 -----
 
--- |Asynchronous exceptions
+-- |Asynchronous exceptions.
 data AsyncException
   = StackOverflow
         -- ^The current thread\'s stack exceeded its limit.
@@ -914,7 +922,7 @@ catchAny :: IO a -> (forall e . Exception e => e -> IO a) -> IO a
 catchAny (IO io) handler = IO $ catch# io handler'
     where handler' (SomeException e) = unIO (handler e)
 
--- | A variant of 'throw' that can be used within the 'IO' monad.
+-- | A variant of 'throw' that can only be used within the 'IO' monad.
 --
 -- Although 'throwIO' has a type that is an instance of the type of 'throw', the
 -- two functions are subtly different:
@@ -975,9 +983,10 @@ blocked = IO $ \s -> case asyncExceptionsBlocked# s of
 \end{code}
 
 \begin{code}
--- | Forces its argument to be evaluated when the resultant 'IO' action
--- is executed.  It can be used to order evaluation with respect to
--- other 'IO' operations; its semantics are given by
+-- | Forces its argument to be evaluated to weak head normal form when
+-- the resultant 'IO' action is executed. It can be used to order
+-- evaluation with respect to other 'IO' operations; its semantics are
+-- given by
 --
 -- >   evaluate x `seq` y    ==>  y
 -- >   evaluate x `catch` f  ==>  (return $! x) `catch` f