POD overhaul

diff --git a/lib/Scope/Context.pm b/lib/Scope/Context.pm
index 85fd57365e7eeacf839251b86a28d9f7075673ca..0bbfd91cc3e15824d414e09e9d7fe6303bdc52b5 100644 (file)
--- a/lib/Scope/Context.pm
+++ b/lib/Scope/Context.pm
@@ -92,7 +92,7 @@ will croak when L</reap> is called.
     my $cxt = Scope::Context->new;
     my $cxt = Scope::Context->new($scope_upper_cxt);
 
-Creates a new immutable L<Scope::Context> object from the L<Scope::Upper>-comptabile context C<$context>.
+Creates a new immutable L<Scope::Context> object from the L<Scope::Upper>-comptabile context identifier C<$context>.
 If omitted, C<$context> defaults to the current context.
 
 =cut
@@ -133,13 +133,13 @@ sub _croak {
 
     my $scope_upper_cxt = $cxt->cxt;
 
-Read-only accessor to the L<Scope::Upper> context corresponding to the topic L<Scope::Context> object.
+Read-only accessor to the L<Scope::Upper> context identifier associated with the invocant.
 
 =head2 C<uid>
 
     my $uid = $cxt->uid;
 
-Read-only accessor to the L<Scope::Upper> UID of the topic L<Scope::Context> object.
+Read-only accessor to the L<Scope::Upper> unique identifier representing the L<Scope::Upper> context associated with the invocant.
 
 =cut
 
@@ -171,7 +171,7 @@ use overload (
 
     my $is_valid = $cxt->is_valid;
 
-Returns true if and only if the topic context is still valid (that is, it designates a scope that is higher than the topic context in the call stack).
+Returns true if and only if the invocant is still valid (that is, it designates a scope that is higher on the call stack than the current scope).
 
 =cut
 
@@ -181,7 +181,7 @@ sub is_valid { Scope::Upper::validate_uid($_[0]->uid) }
 
     $cxt->assert_valid;
 
-Throws an exception if the topic context has expired and is no longer valid.
+Throws an exception if the invocant has expired and is no longer valid.
 Returns true otherwise.
 
 =cut
@@ -198,7 +198,7 @@ sub assert_valid {
 
     my $want = $cxt->want;
 
-Returns the Perl context (in the sense of C<wantarray> : C<undef> for void context, C<''> for scalar context, and true for list context) in which is executed the scope corresponding to the topic L<Scope::Context> object.
+Returns the Perl context (in the sense of C<wantarray> : C<undef> for void context, C<''> for scalar context, and true for list context) in which is executed the scope pointed by the invocant.
 
 =cut
 
@@ -216,9 +216,9 @@ sub want {
     my $up_cxt = $cxt->up($frames);
     my $up_cxt = Scope::Context->up;
 
-Returns a new L<Scope::Context> object pointing to the C<$frames>-th upper scope above the topic context.
+Returns a new L<Scope::Context> object pointing to the C<$frames>-th upper scope above the scope pointed by the invocant.
 
-This method can also be invoked as a class method, in which case it is equivalent to calling L</up> on a L<Scope::Context> object for the current context.
+This method can also be invoked as a class method, in which case it is equivalent to calling L</up> on a L<Scope::Context> object representing the current context.
 
 If omitted, C<$frames> defaults to C<1>.
 
@@ -257,11 +257,11 @@ sub up {
     my $sub_cxt = $cxt->sub($frames);
     my $sub_cxt = Scope::Context->sub;
 
-Returns a new L<Scope::Context> object pointing to the C<$frames>-th subroutine scope above the topic context.
+Returns a new L<Scope::Context> object pointing to the C<$frames>-th subroutine scope above the scope pointed by the invocant.
 
 This method can also be invoked as a class method, in which case it is equivalent to calling L</sub> on a L<Scope::Context> object for the current context.
 
-If omitted, C<$frames> defaults to C<0>, which results in the closest sub enclosing the topic context.
+If omitted, C<$frames> defaults to C<0>, which results in the closest sub enclosing the scope pointed by the invocant.
 
     outer();
 
@@ -301,11 +301,11 @@ sub sub {
     my $eval_cxt = $cxt->eval($frames);
     my $eval_cxt = Scope::Context->eval;
 
-Returns a new L<Scope::Context> object pointing to the C<$frames>-th C<eval> scope above the topic context.
+Returns a new L<Scope::Context> object pointing to the C<$frames>-th C<eval> scope above the scope pointed by the invocant.
 
 This method can also be invoked as a class method, in which case it is equivalent to calling L</eval> on a L<Scope::Context> object for the current context.
 
-If omitted, C<$frames> defaults to C<0>, which results in the closest eval enclosing the topic context.
+If omitted, C<$frames> defaults to C<0>, which results in the closest eval enclosing the scope pointed by the invocant.
 
     eval {
      sub {
@@ -339,7 +339,7 @@ sub eval {
 
     $cxt->reap($code);
 
-Execute C<$code> when the topic context ends.
+Execute C<$code> when the scope pointed by the invocant ends.
 
 See L<Scope::Upper/reap> for details.
 
@@ -357,7 +357,7 @@ sub reap {
 
     $cxt->localize($what, $value);
 
-Localize the variable described by C<$what> to the value C<$value> when the control flow returns to the scope pointed by the topic context.
+Localize the variable described by C<$what> to the value C<$value> when the control flow returns to the scope pointed by the invocant.
 
 See L<Scope::Upper/localize> for details.
 
@@ -375,7 +375,7 @@ sub localize {
 
     $cxt->localize_elem($what, $key, $value);
 
-Localize the element C<$key> of the variable C<$what> to the value C<$value> when the control flow returns to the scope pointed by the topic context.
+Localize the element C<$key> of the variable C<$what> to the value C<$value> when the control flow returns to the scope pointed by the invocant.
 
 See L<Scope::Upper/localize_elem> for details.
 
@@ -393,7 +393,7 @@ sub localize_elem {
 
     $cxt->localize_delete($what, $key);
 
-Delete the element C<$key> from the variable C<$what> when the control flow returns to the scope pointed by the topic context.
+Delete the element C<$key> from the variable C<$what> when the control flow returns to the scope pointed by the invocant.
 
 See L<Scope::Upper/localize_delete> for details.
 
@@ -411,7 +411,7 @@ sub localize_delete {
 
     $cxt->unwind(@values);
 
-Immediately returns the scalars listed in C<@values> from the closest subroutine enclosing the topic context.
+Immediately returns the scalars listed in C<@values> from the closest subroutine enclosing the scope pointed by the invocant.
 
 See L<Scope::Upper/unwind> for details.
 
@@ -429,7 +429,7 @@ sub unwind {
 
     $cxt->yield(@values);
 
-Immediately returns the scalars listed in C<@values> from the topic context, whatever it may be (except a substitution eval context).
+Immediately returns the scalars listed in C<@values> from the scope pointed by the invocant, whatever it may be (except a substitution eval context).
 
 See L<Scope::Upper/yield> for details.
 
@@ -447,7 +447,7 @@ sub yield {
 
     my @ret = $cxt->uplevel($code, @args);
 
-Executes the code reference C<$code> with arguments C<@args> in the same setting as the closest subroutine enclosing the topic context, then returns to the current scope the values returned by C<$code>.
+Executes the code reference C<$code> with arguments C<@args> in the same setting as the closest subroutine enclosing the scope pointed by the invocant, then returns to the current scope the values returned by C<$code>.
 
 See L<Scope::Upper/uplevel> for details.