\end{code}
\begin{code}
--- | Forces its argument to be evaluated, and returns the result in
--- the 'IO' monad. It can be used to order evaluation with respect to
+-- | 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
--
-- > evaluate x `seq` y ==> y
-- > evaluate x >>= f ==> (return $! x) >>= f
--
-- /Note:/ the first equation implies that @(evaluate x)@ is /not/ the
--- same as @(return $! x)@.
+-- same as @(return $! x)@. A correct definition is
+--
+-- > evaluate x = (return $! x) >>= return
+--
evaluate :: a -> IO a
evaluate a = IO $ \s -> case a `seq` () of () -> (# s, a #)
-- NB. can't write