--- Guard/Guard.pm	2008/12/13 18:49:22	1.9
+++ Guard/Guard.pm	2008/12/13 18:53:30	1.12
@@ -109,7 +109,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,7 +135,9 @@
 $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
 
@@ -167,11 +171,14 @@
 (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>