doc tweaks, including more precise equations for evaluate

diff --git a/Control/Exception.hs b/Control/Exception.hs
index f351f87..d789f06 100644 (file)
--- a/Control/Exception.hs
+++ b/Control/Exception.hs
@@ -152,7 +152,7 @@ import Data.Dynamic
 -- argument.  Otherwise, the result is returned as normal.  For example:
 --
 -- >   catch (openFile f ReadMode) 
--- >       (\e -> hPutStr stderr (\"Couldn\'t open \"++f++\": \" ++ show e))
+-- >       (\e -> hPutStr stderr ("Couldn't open "++f++": " ++ show e))
 --
 -- For catching exceptions in pure (non-'IO') expressions, see the
 -- function 'evaluate'.
@@ -251,7 +251,7 @@ mapException f v = unsafePerformIO (catch (evaluate v)
 -- @('Right' a)@ if no exception was raised, or @('Left' e)@ if an
 -- exception was raised and its value is @e@.
 --
--- >  try a = catch (Right \`liftM\` a) (return . Left)
+-- >  try a = catch (Right `liftM` a) (return . Left)
 --
 -- Note: as with 'catch', it is only polite to use this variant if you intend
 -- to re-throw the exception after performing whatever cleanup is needed.

diff --git a/GHC/Exception.lhs b/GHC/Exception.lhs
index 0f9223d..073e7a9 100644 (file)
--- a/GHC/Exception.lhs
+++ b/GHC/Exception.lhs
@@ -106,10 +106,12 @@ unblock (IO io) = IO $ unblockAsyncExceptions# io
 -- the 'IO' monad.  It can be used to order evaluation with respect to
 -- other 'IO' operations; its semantics are given by
 --
--- >   evaluate undefined `seq` return ()  ==> return ()
--- >   catch (evaluate undefined) (\e -> return ())  ==> return ()
+-- >   evaluate x `seq` y    ==>  y
+-- >   evaluate x `catch` f  ==>  (return $! x) `catch` f
+-- >   evaluate x >>= f      ==>  (return $! x) >>= f
 --
--- NOTE: @(evaluate a)@ is /not/ the same as @(a \`seq\` return a)@.
+-- /Note:/ the first equation implies that @(evaluate x)@ is /not/ the
+-- same as @(return $! x)@.
 evaluate :: a -> IO a
 evaluate a = IO $ \s -> case a `seq` () of () -> (# s, a #)
         -- NB. can't write  

diff --git a/GHC/IOBase.lhs b/GHC/IOBase.lhs
index 499899a..3442677 100644 (file)
--- a/GHC/IOBase.lhs
+++ b/GHC/IOBase.lhs
@@ -815,8 +815,8 @@ throw exception = raise# exception
 -- Although 'throwIO' has a type that is an instance of the type of 'throw', the
 -- two functions are subtly different:
 --
--- > throw e   `seq` return ()  ===> throw e
--- > throwIO e `seq` return ()  ===> return ()
+-- > throw e   `seq` x  ===> throw e
+-- > throwIO e `seq` x  ===> x
 --
 -- The first example will cause the exception @e@ to be raised,
 -- whereas the second one won\'t.  In fact, 'throwIO' will only cause