Merge pull request #6 from purescript/docs

Docs, exports

Author: paf31

README.md

@@ -2,26 +2,79 @@
 
 ## Module Control.Monad.Eff.Exception
 
-### Types
 
-    data Error :: *
+This module defines an effect, actions and handlers for working
+with Javascript exceptions.
 
-    data Exception :: !
+#### `Exception`
 
+``` purescript
+data Exception :: !
+```
 
-### Type Class Instances
+This effect is used to annotate code which possibly throws exceptions
 
-    instance showError :: Show Error
+#### `Error`
 
+``` purescript
+data Error :: *
+```
 
-### Values
+The type of Javascript errors
 
-    catchException :: forall a eff. (Error -> Eff eff a) -> Eff (err :: Exception | eff) a -> Eff eff a
+#### `showError`
 
-    error :: String -> Error
+``` purescript
+instance showError :: Show Error
+```
 
-    message :: Error -> String
 
-    showErrorImpl :: Error -> String
+#### `error`
 
-    throwException :: forall a eff. Error -> Eff (err :: Exception | eff) a
+``` purescript
+error :: String -> Error
+```
+
+Create a Javascript error, specifying a message
+
+#### `message`
+
+``` purescript
+message :: Error -> String
+```
+
+Get the error message from a Javascript error
+
+#### `throwException`
+
+``` purescript
+throwException :: forall a eff. Error -> Eff (err :: Exception | eff) a
+```
+
+Throw an exception
+
+For example:
+
+```purescript
+main = do
+  x <- readNumber
+  when (x < 0) $ throwException $ 
+    error "Expected a non-negative number"
+```
+
+#### `catchException`
+
+``` purescript
+catchException :: forall a eff. (Error -> Eff eff a) -> Eff (err :: Exception | eff) a -> Eff eff a
+```
+
+Catch an exception by providing an exception handler.
+
+This handler removes the `Exception` effect.
+
+For example:
+
+```purescript
+main = catchException print do
+  trace "Exceptions thrown in this block will be logged to the console"
+```

src/Control/Monad/Eff/Exception.purs

@@ -1,9 +1,21 @@
-module Control.Monad.Eff.Exception where
+-- | This module defines an effect, actions and handlers for working
+-- | with Javascript exceptions.
+
+module Control.Monad.Eff.Exception 
+  ( Exception()
+  , Error()
+  , error
+  , message
+  , throwException
+  , catchException
+  ) where
 
 import Control.Monad.Eff
 
+-- | This effect is used to annotate code which possibly throws exceptions
 foreign import data Exception :: !
 
+-- | The type of Javascript errors
 foreign import data Error :: *
 
 instance showError :: Show Error where
@@ -16,20 +28,32 @@ foreign import showErrorImpl
   }
   """ :: Error -> String
 
+-- | Create a Javascript error, specifying a message
 foreign import error
   """
   function error(msg) {
     return new Error(msg);
   }
   """ :: String -> Error
 
+-- | Get the error message from a Javascript error
 foreign import message
   """
   function message(e) {
     return e.message;
   }
   """ :: Error -> String
 
+-- | Throw an exception
+-- |
+-- | For example:
+-- |
+-- | ```purescript
+-- | main = do
+-- |   x <- readNumber
+-- |   when (x < 0) $ throwException $ 
+-- |     error "Expected a non-negative number"
+-- | ```
 foreign import throwException
   """
   function throwException(e) {
@@ -39,6 +63,16 @@ foreign import throwException
   }
   """ :: forall a eff. Error -> Eff (err :: Exception | eff) a
 
+-- | Catch an exception by providing an exception handler.
+-- |
+-- | This handler removes the `Exception` effect.
+-- |
+-- | For example:
+-- |
+-- | ```purescript
+-- | main = catchException print do
+-- |   trace "Exceptions thrown in this block will be logged to the console"
+-- | ```
 foreign import catchException
   """
   function catchException(c) {