Documentation of Control.Exception should take better account of imprecise exceptions
The documentation for throwIO
currently says
Although throwIO has a type that is an instance of the type of throw, the two functions are subtly different:
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.
But throw e `seq` x ===> throw e
will only hold if x
doesn't diverge itself due to imprecise exception semnatics, so that reduction is plain wrong.
We should also very explicitly document the fact that throw
throws an imprecise exception, whereas throwIO
throws a precise exception and give a short example of imprecise exception semantics. Currently, the distinction is not very prominent at all in the haddocks and a bit scattered between the module haddock and evaluate
. There's no clear line that says "It is undefined whether error "foo"
seq error "bar"
throws foo
or bar
", or generally that a `seq` b === b `seq` a
. Also it would help to point to pseq
as a pure alternative to evaluate
.