--- Guard/Guard.pm	2008/12/13 18:49:22	1.9
+++ Guard/Guard.pm	2008/12/13 22:09:25	1.15
@@ -12,7 +12,7 @@
       scope_guard { chdir "/" };
       chdir "/etc";
    
-      call_function_that_might_die_or_other_fun_stuff;
+      code_that_might_die_or_does_other_fun_stuff;
    }
 
 =head1 DESCRIPTION
@@ -36,8 +36,10 @@
 
 package Guard;
 
+no warnings;
+
 BEGIN {
-   $VERSION = '0.1';
+   $VERSION = '0.5';
    @ISA = qw(Exporter);
    @EXPORT = qw(guard scope_guard);
 
@@ -109,7 +111,9 @@
 (i.e. C<die>) are handled inside guard blocks.
 
 Example: acquire a Coro::Semaphore for a second by registering a
-timer. The timer callback references the guard used to unlock it again.
+timer. The timer callback references the guard used to unlock it
+again. (Please ignore the fact that C<Coro::Semaphore> has a C<guard>
+method that does this already):
 
    use Guard;
    use AnyEvent;
@@ -133,9 +137,11 @@
 $sem->down >> in the callback is that you can opt not to create the timer,
 or your code can throw an exception before it can create the timer, or you
 can create multiple timers or other event watchers and only when the last
-one gets executed will the lock be unlocked.
+one gets executed will the lock be unlocked. Using the C<guard>, you do
+not have to worry about catching all the places where you have to unlock
+the semaphore.
 
-=item Guard::cancel $guard
+=item $guard->cancel
 
 Calling this function will "disable" the guard object returned by the
 C<guard> function, i.e. it will free the BLOCK originally passed to
@@ -158,20 +164,23 @@
 to die. Also, programming errors are a large source of exceptions, and the
 programmer certainly wants to know about those.
 
-Since in most cases, the block executing when the guard gets executes does
+Since in most cases, the block executing when the guard gets executed does
 not know or does not care about the guard blocks, it makes little sense to
 let containing code handle the exception.
 
 Therefore, whenever a guard block throws an exception, it will be caught,
-and this module will call the code reference stored in C<$Guard::DIED>
-(with C<$@> set to the actual exception), which is similar to how most
-event loops handle this case.
+followed by calling the code reference stored in C<$Guard::DIED> (with
+C<$@> set to the actual exception), which is similar to how most event
+loops handle this case.
+
+The default for C<$Guard::DIED> is to call C<warn "$@">.
+
+The C<$@> variable will be restored to its value before the guard call in
+all cases, so guards will not disturb C<$@> in any way.
 
 The code reference stored in C<$Guard::DIED> should not die (behaviour is
 not guaranteed, but right now, the exception will simply be ignored).
 
-The default for C<$Guard::DIED> is to call C<warn "$@">.
-
 =head1 AUTHOR
 
  Marc Lehmann <schmorp@schmorp.de>