Update docs

Author: garyb

README.md

@@ -6,16 +6,16 @@
 
 An asynchronous effect monad for PureScript.
 
-The moral equivalent of `ErrorT (ContT Unit (Eff e) a`, for effects `e`.
+The moral equivalent of `ErrorT (ContT Unit (Eff e)) a`, for effects `e`.
 
 `Aff` lets you say goodbye to monad transformers and callback hell!
 
 # Example
 
 ```purescript
-main = launchAff $ 
-  do response <- Ajax.get "http://foo.bar"
-     liftEff $ log response.body
+main = launchAff do
+  response <- Ajax.get "http://foo.bar"
+  liftEff $ log response.body
 ```
 
 See the [tests](https://github.com/slamdata/purescript-aff/blob/master/test/Test/Main.purs) for more examples.
@@ -33,10 +33,10 @@ bower install purescript-aff
 An example of `Aff` is shown below:
 
 ```purescript
-deleteBlankLines path =
-  do  contents <- loadFile path
-      let contents' = S.join "\n" $ A.filter (\a -> S.length a > 0) (S.split "\n" contents)
-      saveFile path contents'
+deleteBlankLines path = do
+  contents <- loadFile path
+  let contents' = S.join "\n" $ A.filter (\a -> S.length a > 0) (S.split "\n" contents)
+  saveFile path contents'
 ```
 
 This looks like ordinary, synchronous, imperative code, but actually operates asynchronously without any callbacks. Error handling is baked in so you only deal with it when you want to.
@@ -149,23 +149,23 @@ Here's an example of how you can use them:
 
 ```purescript
 do resp <- (Ajax.get "http://foo.com") `catchError` (const $ pure defaultResponse)
-   if resp.statusCode != 200 then throwError myErr 
+   if resp.statusCode != 200 then throwError myErr
    else pure resp.body
 ```
 
 Thrown exceptions are propagated on the error channel, and can be recovered from using `attempt` or `catchError`.
 
 ## Forking
 
-Using the `forkAff`, you can "fork" an asynchronous computation, which means 
+Using the `forkAff`, you can "fork" an asynchronous computation, which means
 that its activities will not block the current thread of execution:
 
 ```purescript
 forkAff myAff
 ```
 
-Because Javascript is single-threaded, forking does not actually cause the 
-computation to be run in a separate thread. Forking just allows the subsequent 
+Because Javascript is single-threaded, forking does not actually cause the
+computation to be run in a separate thread. Forking just allows the subsequent
 actions to execute without waiting for the forked computation to complete.
 
 If the asynchronous computation supports it, you can "kill" a forked computation
@@ -191,28 +191,34 @@ The `Control.Monad.Aff.AVar` module contains asynchronous variables, which are v
 ```purescript
 do v <- makeVar
    forkAff (later $ putVar v 1.0)
-   a <- takeVar v 
+   a <- takeVar v
    liftEff $ log ("Succeeded with " ++ show a)
 ```
 
-You can use these constructs as one-sided blocking queues, which suspend (if 
+You can use these constructs as one-sided blocking queues, which suspend (if
 necessary) on `take` operations, or as asynchronous, empty-or-full variables.
 
 ## Parallel Execution
 
-If you only need the power of `Applicative`, then instead of using the monadic `Aff`, you can use the `Par` newtype wrapper defined in `Control.Monad.Aff.Par`.
+There are `MonadPar` and `MonadRace` instances defined for `Aff`, allowing for parallel execution of `Aff` computations.
 
-This provides parallel instances of `Apply` and `Alt`.
+There are two ways of taking advantage of these instances - directly through the `par` and `race` functions from these classes, or by using the `Parallel` newtype wrapper that enables parallel behaviours through the `Applicative` and `Alternative` operators.
 
-In the following example, two Ajax requests are initiated simultaneously (rather than in sequence, as they would be for `Aff`):
+In the following example, using the newtype, two Ajax requests are initiated simultaneously (rather than in sequence, as they would be for `Aff`):
 
 ```purescript
-runPar (f <$> Par (Ajax.get "http://foo.com") <*> Par (Ajax.get "http://foo.com"))
+runParallel (f <$> parallel (Ajax.get "http://foo.com") <*> parallel (Ajax.get "http://foo.com"))
 ```
 
-The `(<|>)` operator of the `Alt` instance of `Par` allows you to race two asynchronous computations, and use whichever value comes back first (or the first error, if both err).
+And the equivalent using the `MonadPar` function directly:
 
-The `runPar` function allows you to unwrap the `Aff` and return to normal monadic (sequential) composition.
+```purescript
+par f (Ajax.get "http://foo.com") (Ajax.get "http://foo.com")
+```
+
+The `race` function from `MonadPar` or the `(<|>)` operator of the `Alt` instance of `Parallel` allows you to race two asynchronous computations, and use whichever value comes back first (or the first error, if both err).
+
+The `runParallel` function allows you to unwrap the `Aff` and return to normal monadic (sequential) composition.
 
 A parallel computation can be canceled if both of its individual components can be canceled.