Clarify some examples

diff --git a/lib/Scope/Context.pm b/lib/Scope/Context.pm
index 7bf5c8c4e9d01c4c85ae5e44b105fc7a0b84a2ad..4f327a30a92c06f85d9bdd2479d8f7cc97d77cd6 100644 (file)
--- a/lib/Scope/Context.pm
+++ b/lib/Scope/Context.pm
@@ -29,7 +29,7 @@ our $VERSION = '0.01';
     for (1 .. 5) {
      sub {
       eval {
-       # create Scope::Context objects
+       # Create Scope::Context objects for different upper frames.
        my ($block, $sub, $eval, $loop);
        {
         $block = Scope::Context->new;
@@ -46,7 +46,7 @@ our $VERSION = '0.01';
        # This prints "hello" when the eval block above ends.
        $eval->reap(sub { print "hello\n" });
 
-       # Ignore $SIG{__DIE__} just for the loop.
+       # Ignore $SIG{__DIE__} just for the loop body.
        $loop->localize_delete('%SIG', '__DIE__');
 
        # Execute the callback as if it ran in place of the sub.
@@ -56,8 +56,15 @@ our $VERSION = '0.01';
 
        # Immediately return (1, 2, 3) from the sub, bypassing the eval.
        $sub->unwind(@values, 3);
+
+       # Not reached.
       }
+
+      # Not reached.
      }->();
+
+     # unwind() returns here. "hello\n" was printed, and now
+     # $SIG{__DIE__} is undefined.
     }
 
 =head1 DESCRIPTION
@@ -70,11 +77,11 @@ This gives you a prettier and safer interface when you are not reaching for extr
 The L<Scope::Context> methods actually do more than their subroutine counterparts from L<Scope::Upper> : before each call, the target context will be checked to ensure it is still active (which means that it is still present in the current call stack), and an exception will be thrown if you attempt to act on a context that has already expired.
 This means that :
 
-    my $sc;
+    my $cxt;
     {
-     $sc = Scope::Context->new;
+     $cxt = Scope::Context->new;
     }
-    $sc->reap(sub { print "hello\n });
+    $cxt->reap(sub { print "hello\n });
 
 will croak when L</reap> is called.
 
@@ -241,7 +248,7 @@ If omitted, C<$frames> defaults to C<0>, which results in the closest sub enclos
     }
 
     sub inner {
-     my $sub = Scope::Context->new->sub(1); # = Scope::Context->sub
+     my $sub = Scope::Context->new->sub(1); # = Scope::Context->sub(1)
      # $sub points to the context for the outer() sub.
     }