Control.Monad.Error documentation

[Andriy Palamarchuk]

Documentation for the Error monad.

Please take a minute to review it. This is one those parts of the library newbies have difficulties to understand. Hopefully good documentation will help them.

Converted the module documentation to Haddock format. Per Jeff Newbern's gracious permission included relevant information, an example from his cool tutorial "All About Monads" http://www.nomaware.com/monads/. Added an example for ErrorT. Use String instead of [Char].

The source of the updated Error module and haddock output for it are attached to the proposal tracker entry:
http://hackage.haskell.org/trac/ghc/ticket/1059

Deadline for the proposal - 2 weeks.


A few questions:

1) What "| m -> e" part means in a declaration:

class (Monad m) => MonadError e m | m -> e where
    throwError :: e -> m a
    catchError :: m a -> (e -> m a) -> m a

2) Can somebody explain what mapErrorT function is used for?

Here is its definition and implementation:

mapErrorT :: (m (Either e a) -> n (Either e' b)) -> ErrorT e m a -> ErrorT e' n b
mapErrorT f m = ErrorT $ f (runErrorT m)

3) I noticed that some examples of a combined ErrorT IO monad use 'lift' function to lift IO operations into IO monad, others use 'liftIO'.
As I understand 'liftIO' can lift operation through a few monad layers to an IO monad in a monad stack while 'lift' lifts operation to the next monad.
If my understanding is correct then 'liftIO' seems a better choice for the example, because the monad stack can be extended later without breaking calls to the IO operations.

4) Is it Ok to say "Haddock for X" instead of "Haddock documentation for X" like in Java people say "Javadoc for X"?
It is funnier if one remembers that haddock is a fish :-)

Corrections, suggestions, comments, better examples?
Thanks,
Andriy



__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around 
http://mail.yahoo.com