Update the docs to reflect guard changes

Fix #4

Author: Enrico Granata

manual.md

@@ -982,9 +982,11 @@ To help with defining a coherent set of comparison operators, the standard libra
 
 ## 👮 Guards
 
-A guard statement is used to create a scoped block that can deallocate some managed resource on exit.
+A guard is used to create a scoped block that can deallocate some managed resource on exit. Note that a `guard`'s `do` block is not a lexical block, but it accepts a function (or really any callable object) that is invoked with the guarded object as argument. This means that the guarded object can outlive the `do` block if it is returned or stored somewhere else. It also means that the `do` block can capture variables from its caller scope, but these will be treated as captures, not as local variables.
 
 ```
+import guard from aria.utils.guard;
+
 struct LoggedTask {
     type func new(op) {
         println("Starting {0}...".format(op));
@@ -999,20 +1001,26 @@ struct LoggedTask {
 }
 
 func main() {
-    guard op1 = LoggedTask.new("first task") { # prints Starting first task...
+    guard(LoggedTask.new("first task")).do(|x| => { # prints Starting first task...
         # do the thing
-    } # prints first task completed
+    }); # prints first task completed
 
-    guard op2 = LoggedTask.new("second task") { # prints Starting second task...
+    guard(LoggedTask.new("second task")).do(|x| => { # prints Starting second task...
         # do the thing
-    } # prints second task completed
+    }); # prints second task completed
 }
 ```
 
 In the general case, objects are deallocated transparently by the Aria VM, and there is no way to control the time and flow of the deallocation.
 
 If an object needs to execute some custom cleanup, a `guard` block is the right way to assign additional behavior independent of the general VM deallocation. Note that an object can live outside of its guard block, and it's up to the object to respond safely to that.
 
+`guard`s return a `Result` based on what their `do` block returns:
+- if the block returns normally with a value, the guard returns `Result::Ok(value);
+- if the block returns with a `Result::Ok(value)`, the guard returns `Result::Ok(value);
+- if the block returns with a `Result::Err(err)`, the guard returns `Result::Err(err)`;
+- if the block throws an exception, the guard re-throws it.
+
 ## 🥗 Mixins
 
 Mixins can be used to insert new behavior into existing types. Aria does not provide inheritance, but some cases can instead be expressed via a `mixin`.

stdlib.md

@@ -1213,6 +1213,33 @@ This module provides the core components for defining test cases and organizing
     *   `add_test(test)`: Adds a `TestCase` instance to the suite. Returns the `TestSuite` instance for chaining.
     *   `run(silent=false)`: Executes all test cases added to the suite. Prints the result of each test and a summary of passed/failed tests. Returns the number of failed tests. If `silent` is `true`, it suppresses the test runner's output during execution.
 
+---
+
+# `aria.utils` Module Reference
+
+This document provides a reference for the `aria.utils` module, which contains utility functions and types for common programming tasks.
+
+---
+
+## Modules
+
+### `aria.utils.guard`
+
+This module provides the implementation for `guard`, a resource management utility.
+
+#### **Functions**
+
+*   **`guard(obj)`**
+    Creates a new `GuardImpl` that wraps the provided object `obj`. The `obj` may optionally define a `guard_exit()` method, which will be called when the guard completes execution.
+
+#### **Structs**
+
+*   **`GuardImpl`**
+    A wrapper for a managed resource that ensures a cleanup function is called when the guard completes execution.
+
+    **Methods:**
+    *   `do(f)`: Runs `f` passing the guarded object as its sole argument. On completion, calls the cleanup function (`guard_exit`) on the guarded object, if one is provided. It returns a `Result` equivalent to `f(...)??`, or re-throws, if `f` throws.
+
 ---
 # Built-in Values