a couple minor fixes in tests, docs and code

Author: OlegZee

XakeLibTests/ActionTests.fs

@@ -289,7 +289,6 @@ let ``try finally fail``() =
 let ``exception handling with 'try with'``() =
 
     let errorlist = makeStringList()
-    let note = errorlist.Add
     let anote txt = action {
         do errorlist.Add txt
     }
@@ -304,8 +303,7 @@ let ``exception handling with 'try with'``() =
             do! anote "try"
             failwith "Ouch"
         with e ->
-            printfn "Finally executed"
-            do note e.Message
+            do! anote e.Message
 
         do! anote "4"
       })

core/Action.fs

@@ -39,9 +39,9 @@ module Action =
           } |> Action
 
       let tryFinallyF body comp = // (body:Action<'a,'b>) -> (comp: unit -> unit) -> Action<'a,'b> =
-          fun (r, a) -> async {
+          fun x -> async {
               try
-                  return! runAction body (r,a)
+                  return! runAction body x
               finally
                   do comp()
           } |> Action

docs/implnotes.md

@@ -31,6 +31,26 @@ Error handling assumes the following system behavior:
 
 ### Implemented ideas
 
+#### try/with/finally exception handling
+`action` computation expression supports try/with and try/finally blocks.
+
+```fsharp
+action {
+  do! log "before try"
+
+  try
+    try
+        do! log "Body executed"
+        failwith "Ouch"
+    with e ->
+        do! log "Exception: %s" e.Message
+  finally
+    printfn "Error!"
+}
+```
+
+> actions (with do! notation) are allowed in `with` block but aren't in `finally` block. This is limitation of F#'s computation expressions.
+
 #### WhenError function
 Intercepts errors (exceptions) and allows to define a custom handler.
 ```
@@ -49,10 +69,6 @@ do! _system [shellcmd] "dir" |> FailWhen ((<>) 0) "Failed to list files in folde
 do! _system [shellcmd] "dir" |> CheckErrorLevel
 ```
 
-#### try/with/finally exception handling
-`action` computation expression supports try/with and try/finally blocks. In most cases these constructs are more
-elegant than using WhenError.
-
 ### Other ideas
 
 // or even that:
@@ -66,8 +82,6 @@ do! _system [fail_on_error; shellcmd; startin "./bin"] "dir"
 // where shellcmd and fail_on_error are functions
 ```
 
-Let action be provided as finally argument.
-
 ### Ideas
 Implemented IgnoreErrors.
 

docs/overview.md

@@ -3,7 +3,7 @@
 **Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
 
   - [The first script](#the-first-script)
-    - [Boostrapping Xake.Core](#boostrapping-xakecore)
+    - [Bootstrapping Xake.Core](#bootstrapping-xakecore)
   - [So what?](#so-what)
     - [Dependencies tracking](#dependencies-tracking)
     - [Running multiple rules in parallel](#running-multiple-rules-in-parallel)
@@ -18,6 +18,7 @@
     - [wantOverride](#wantoverride)
   - [action computation](#action-computation)
     - [Tasks, `do!` notation](#tasks-do-notation)
+    - [Exception handling](#exception-handling)
     - [need](#need)
     - [Filesets](#filesets)
     - [Other functions](#other-functions)
@@ -62,7 +63,7 @@ Here are we doing the following steps:
 1. specify the default target ("main") requires "hw.exe" target
 1. define the rule for "hw.exe" target
 
-### Boostrapping Xake.Core
+### Bootstrapping Xake.Core
 
 The steps above assumes you've downloaded xake core assembly to .tools folder.
 The next script demonstrates how to create the build script that does not require any installation steps:
@@ -290,11 +291,11 @@ If the task (action) returns a value which you do not need use Action.Ignore:
 ```fsharp
   action {
     do! system "ls" [] |> Action.Ignore
-    if error_code <> 0 then failwith...
   }
 ```
 
 ### Exception handling
+
 `action` block allows to handle exceptions with idiomatic try/with and try/finally blocks.
 ```fsharp
     phony "main" (action {
@@ -304,14 +305,13 @@ If the task (action) returns a value which you do not need use Action.Ignore:
             do! trace Level.Info "try"
             failwith "Ouch"
         with e ->
-            printfn "Error '%s' occured" e.Message
+            do! trace Level.Error "Error '%s' occured" e.Message
       finally
           printfn "Finally executed"
-        
       printfn "execution continues after try blocks"
     })
 ```
-Notice `trace` function just like any other actions cannot be used inside `with` and `finally` blocks due to language limitations.
+Notice `trace` function just like any other actions (do! notation) cannot be used in `finally` blocks due to language limitations.
 
 `WhenError` function is another option to handle errors.
 ```fsharp