add async trace and improve docs

Author: jdegoes

Gruntfile.js

@@ -47,6 +47,6 @@ module.exports = function(grunt) {
   grunt.loadNpmTasks('grunt-jsvalidate');
 
   grunt.registerTask("make", ["pscMake", "jsvalidate", "dotPsci", "pscDocs"]);
-  grunt.registerTask("test", ["jsvalidate", "psc"]);
+  grunt.registerTask("test", ["jsvalidate", "psc", "pscDocs"]);
   grunt.registerTask("default", ["make"]);
 };

MODULES.md

@@ -8,8 +8,8 @@
 data Aff :: # ! -> * -> *
 ```
 
-A computation with effects `e`. The computation either errors or
-produces a value of type `a`.
+An asynchronous computation with effects `e`. The computation either 
+errors or produces a value of type `a`.
 
 This is moral equivalent of `ErrorT (ContT Unit (Eff e)) a`.
 
@@ -19,7 +19,8 @@ This is moral equivalent of `ErrorT (ContT Unit (Eff e)) a`.
 type PureAff a = forall e. Aff e a
 ```
 
-A pure asynchronous computation, having no effects.
+A pure asynchronous computation, having no effects other than 
+asynchronous computation.
 
 #### `Canceler`
 
@@ -30,7 +31,9 @@ newtype Canceler e
 
 A canceler is asynchronous function that can be used to attempt the 
 cancelation of a computation. Returns a boolean flag indicating whether
-or not the cancellation was successful.
+or not the cancellation was successful. Many computations may be composite,
+in such cases the flag indicates whether any part of the computation was 
+successfully canceled. The flag should not be used for communication.
 
 #### `cancel`
 
@@ -102,17 +105,21 @@ Runs the asynchronous computation off the current execution context.
 later' :: forall e a. Number -> Aff e a -> Aff e a
 ```
 
-Runs the asynchronous computation later (off the current execution context).
+Runs the specified asynchronous computation later, by the specified 
+number of milliseconds.
 
 #### `forkAff`
 
 ``` purescript
 forkAff :: forall e a. Aff e a -> Aff e (Canceler e)
 ```
 
-Forks the specified asynchronous computation so subsequent monadic binds
+Forks the specified asynchronous computation so subsequent computations
 will not block on the result of the computation.
 
+Returns a canceler that can be used to attempt cancellation of the 
+forked computation.
+
 #### `attempt`
 
 ``` purescript
@@ -143,7 +150,7 @@ Lifts a synchronous computation and makes explicit any failure from exceptions.
 nonCanceler :: forall e. Canceler e
 ```
 
-A constant function that always returns a pure false value.
+A constant canceller that always returns false.
 
 #### `semigroupAff`
 
@@ -344,6 +351,18 @@ instance monadAffAff :: MonadAff e (Aff e)
 
 
 
+## Module Control.Monad.Aff.Debug.Trace
+
+#### `trace`
+
+``` purescript
+trace :: forall e a. (Show a) => a -> Aff (trace :: T.Trace | e) a
+```
+
+Traces any `Show`-able value to the console. This basically saves you 
+from writing `liftEff $ trace x` everywhere.
+
+
 ## Module Control.Monad.Aff.Par
 
 #### `Par`

examples/src/Examples.purs

@@ -1,148 +1,149 @@
 module Examples where 
-  import Debug.Trace(trace, Trace())
+  import Debug.Trace(Trace())
 
   import Data.Either(either)
 
   import Control.Monad.Aff
   import Control.Monad.Aff.AVar
   import Control.Monad.Aff.Par
+  import Control.Monad.Aff.Debug.Trace(trace)
   import Control.Apply((*>))
   import Control.Alt(Alt, (<|>))
   import Control.Monad.Eff.Class(liftEff)
   import Control.Monad.Eff.Exception(error)
   import Control.Monad.Error.Class(throwError)
 
-  type Test = forall e. Aff (trace :: Trace | e) Unit
-  type TestAVar = forall e. Aff (trace :: Trace, avar :: AVAR | e) Unit
+  type Test a = forall e. Aff (trace :: Trace | e) a
+  type TestAVar a = forall e. Aff (trace :: Trace, avar :: AVAR | e) a
 
-  test_sequencing :: Number -> Test
-  test_sequencing 0 = liftEff $ trace "Done"
+  test_sequencing :: Number -> Test _
+  test_sequencing 0 = trace "Done"
   test_sequencing n = do
-    later' 100 (liftEff $ trace (show (n / 10) ++ " seconds left"))
+    later' 100 (trace (show (n / 10) ++ " seconds left"))
     test_sequencing (n - 1)
 
-  test_pure :: Test
+  test_pure :: Test _
   test_pure = do
     pure unit 
     pure unit
     pure unit
-    liftEff $ trace "Success: Got all the way past 4 pures"
+    trace "Success: Got all the way past 4 pures"
 
-  test_attempt :: Test
+  test_attempt :: Test _
   test_attempt = do
     e <- attempt (throwError (error "Oh noes!"))
-    liftEff $ either (const $ trace "Success: Exception caught") (const $ trace "Failure: Exception NOT caught!!!") e
+    either (const $ trace "Success: Exception caught") (const $ trace "Failure: Exception NOT caught!!!") e
 
-  test_apathize :: Test
+  test_apathize :: Test _
   test_apathize = do
     apathize $ throwError (error "Oh noes!")
-    liftEff $ trace "Success: Exceptions don't stop the apathetic"
+    trace "Success: Exceptions don't stop the apathetic"
 
-  test_putTakeVar :: TestAVar
+  test_putTakeVar :: TestAVar _
   test_putTakeVar = do
     v <- makeVar
     forkAff (later $ putVar v 1.0)
     a <- takeVar v 
-    liftEff $ trace ("Success: Value " ++ show a)
+    trace ("Success: Value " ++ show a)
 
-  test_killFirstForked :: Test
+  test_killFirstForked :: Test _
   test_killFirstForked = do 
     c <- forkAff (later' 100 $ pure "Failure: This should have been killed!")
     b <- c `cancel` (error "Just die")
-    liftEff $ trace (if b then "Success: Killed first forked" else "Failure: Couldn't kill first forked")
+    trace (if b then "Success: Killed first forked" else "Failure: Couldn't kill first forked")
 
 
-  test_killVar :: TestAVar
+  test_killVar :: TestAVar _
   test_killVar = do
     v <- makeVar
     killVar v (error "DOA")
     e <- attempt $ takeVar v
-    liftEff $ either (const $ trace "Success: Killed queue dead") (const $ trace "Failure: Oh noes, queue survived!") e
+    either (const $ trace "Success: Killed queue dead") (const $ trace "Failure: Oh noes, queue survived!") e
 
-  test_parRace :: TestAVar
+  test_parRace :: TestAVar _
   test_parRace = do
     s <- runPar (Par (later' 100 $ pure "Success: Early bird got the worm") <|> 
                  Par (later' 200 $ pure "Failure: Late bird got the worm"))
-    liftEff $ trace s
+    trace s
 
-  test_parRaceKill1 :: TestAVar
+  test_parRaceKill1 :: TestAVar _
   test_parRaceKill1 = do
     s <- runPar (Par (later' 100 $ throwError (error ("Oh noes!"))) <|> 
                  Par (later' 200 $ pure "Success: Early error was ignored in favor of late success"))
-    liftEff $ trace s
+    trace s
 
-  test_parRaceKill2 :: TestAVar
+  test_parRaceKill2 :: TestAVar _
   test_parRaceKill2 = do
     e <- attempt $ runPar (Par (later' 100 $ throwError (error ("Oh noes!"))) <|> 
                            Par (later' 200 $ throwError (error ("Oh noes!"))))
-    liftEff $ either (const $ trace "Success: Killing both kills it dead") (const $ trace "Failure: It's alive!!!") e
+    either (const $ trace "Success: Killing both kills it dead") (const $ trace "Failure: It's alive!!!") e
 
-  test_semigroupCanceler :: Test
+  test_semigroupCanceler :: Test _
   test_semigroupCanceler = 
     let 
       c = Canceler (const (pure true)) <> Canceler (const (pure true))
     in do 
       v <- cancel c (error "CANCEL")
-      liftEff $ trace (if v then "Success: Canceled semigroup composite canceler" 
+      trace (if v then "Success: Canceled semigroup composite canceler" 
                        else "Failure: Could not cancel semigroup composite canceler")
 
-  test_cancelLater :: TestAVar
+  test_cancelLater :: TestAVar _
   test_cancelLater = do
     c <- forkAff $ (do pure "Binding"
-                       _ <- later' 100 $ liftEff $ trace ("Failure: Later was not canceled!")
+                       _ <- later' 100 $ trace ("Failure: Later was not canceled!")
                        pure "Binding")
     v <- cancel c (error "Cause")
-    liftEff $ trace (if v then "Success: Canceled later" else "Failure: Did not cancel later")
+    trace (if v then "Success: Canceled later" else "Failure: Did not cancel later")
 
-  test_cancelPar :: TestAVar
+  test_cancelPar :: TestAVar _
   test_cancelPar = do
-    c  <- forkAff <<< runPar $ Par (later' 100 $ liftEff $ trace "Failure: #1 should not get through") <|>
-                               Par (later' 100 $ liftEff $ trace "Failure: #2 should not get through")
+    c  <- forkAff <<< runPar $ Par (later' 100 $ trace "Failure: #1 should not get through") <|>
+                               Par (later' 100 $ trace "Failure: #2 should not get through")
     v  <- c `cancel` (error "Must cancel")
-    liftEff $ trace (if v then "Success: Canceling composite of two Par succeeded" 
+    trace (if v then "Success: Canceling composite of two Par succeeded" 
                      else "Failure: Canceling composite of two Par failed")
 
   main = launchAff $ do
-    liftEff $ trace "Testing sequencing"
+    trace "Testing sequencing"
     test_sequencing 3
 
-    liftEff $ trace "Testing pure"
+    trace "Testing pure"
     test_pure
 
-    liftEff $ trace "Testing attempt"
+    trace "Testing attempt"
     test_attempt
 
-    liftEff $ trace "Testing later"
-    later $ liftEff $ trace "Success: It happened later"
+    trace "Testing later"
+    later $ trace "Success: It happened later"
 
-    liftEff $ trace "Testing kill of later"
+    trace "Testing kill of later"
     test_cancelLater
 
-    liftEff $ trace "Testing kill of first forked"
+    trace "Testing kill of first forked"
     test_killFirstForked
 
-    liftEff $ trace "Testing apathize"
+    trace "Testing apathize"
     test_apathize
 
-    liftEff $ trace "Testing semigroup canceler"
+    trace "Testing semigroup canceler"
     test_semigroupCanceler
 
-    liftEff $ trace "Testing AVar - putVar, takeVar"
+    trace "Testing AVar - putVar, takeVar"
     test_putTakeVar
 
-    liftEff $ trace "Testing AVar killVar"
+    trace "Testing AVar killVar"
     test_killVar
 
-    liftEff $ trace "Testing Par (<|>)"
+    trace "Testing Par (<|>)"
     test_parRace
 
-    liftEff $ trace "Testing Par (<|>) - kill one"
+    trace "Testing Par (<|>) - kill one"
     test_parRaceKill1
 
-    liftEff $ trace "Testing Par (<|>) - kill two"
+    trace "Testing Par (<|>) - kill two"
     test_parRaceKill2
 
-    liftEff $ trace "Testing cancel of Par (<|>)"
+    trace "Testing cancel of Par (<|>)"
     test_cancelPar
 
-    liftEff $ trace "Done testing"
+    trace "Done testing"