Put a warning about how ExceptT is different from Control.Exception
authorSaurabh Nanda <saurabh@vacationlabs.com>
Mon, 20 Nov 2017 14:35:52 +0000 (20:05 +0530)
committerGitHub <noreply@github.com>
Mon, 20 Nov 2017 14:35:52 +0000 (20:05 +0530)
We have been bitten by this confusion first-hand and would like to prevent others from having this experience.

Control/Monad/Except.hs

index 178927d..e9a5a9a 100644 (file)
@@ -31,6 +31,8 @@ The Error monad (also called the Exception monad).
 -}
 module Control.Monad.Except
   (
+    -- * Warning
+    -- $warning
     -- * Monads with error handling
     MonadError(..),
     liftEither,
@@ -71,6 +73,18 @@ import Control.Monad.Fix
 import Control.Monad.Instances ()
 #endif
 
+{- $warning
+Please do not confuse 'ExceptT' and 'throwError' with 'Contorl.Exception.Exception' / 
+'Control.Exception.SomeException' and 'Control.Exception.catch', respectively. The latter
+are for exceptions built into GHC, by default, and are mostly used from within the IO monad.
+They and do not interact with the "exceptions" in this package at all. This package allows you
+to define a new kind of exception control mechanism which does not necessarily need your code to
+be placed in the IO monad.
+
+In short, all "catching" mechanims in this library will be unable to catch exceptions thrown 
+by functions in the 'Control.Exception' package, and vice-versa.
+-}
+
 {- $customErrorExample
 Here is an example that demonstrates the use of a custom error data type with
 the 'throwError' and 'catchError' exception mechanism from 'MonadError'.