[Moose-commits] r7492 - Moose/trunk/lib/Moose/Manual

[autarch at code2.0beta.co.uk]

Author: autarch
Date: 2009-02-03 08:45:27 -0800 (Tue, 03 Feb 2009)
New Revision: 7492

Modified:
   Moose/trunk/lib/Moose/Manual/MethodModifiers.pod
Log:
Various tweaks to MethodModifiers document


Modified: Moose/trunk/lib/Moose/Manual/MethodModifiers.pod
===================================================================
--- Moose/trunk/lib/Moose/Manual/MethodModifiers.pod	2009-02-03 16:39:00 UTC (rev 7491)
+++ Moose/trunk/lib/Moose/Manual/MethodModifiers.pod	2009-02-03 16:45:27 UTC (rev 7492)
@@ -2,12 +2,12 @@
 
 =head1 NAME
 
-Moose::Manual::Attribute - Moose's Method Modifiers
+Moose::Manual::MethodModifiers - Moose's Method Modifiers
 
 =head1 WHAT IS A METHOD MODIFIER?
 
-Moose provides a feature called "method modifiers". Another word for
-this feature might be "hooks" or "advice".
+Moose provides a feature called "method modifiers". You can also think
+of these as "hooks" or "advice".
 
 It's probably easiest to understand this feature with a few examples:
 
@@ -65,11 +65,11 @@
 
 Method modifiers have many uses. One very common use is in roles. This
 lets roles alter the behavior of methods in the classes that use
-them. See L<Moose::Manual::Roles> for more about roles.
+them. See L<Moose::Manual::Roles> for more information about roles.
 
-Modifiers really are at their most useful in roles, so some of the
+Most of the modifiers are most useful in roles, so some of the
 examples below are a bit artificial. They're intended to give you an
-idea of how modifiers work, but may not be the most natural usages.
+idea of how modifiers work, but may not be the most natural usage.
 
 =head1 BEFORE, AFTER, AND AROUND
 
@@ -96,8 +96,9 @@
           if @_ && $self->is_growing;
   };
 
-This lets us implement logical checks that don't fit well into
-constraints.
+This lets us implement logical checks that don't make sense as type
+constraints. In particular, they're useful for defining logical rules
+about an object's state changes.
 
 Similarly, an after modifier could be used for logging an action that
 was taken.
@@ -106,11 +107,10 @@
 ignored.
 
 An around modifier is a bit more powerful than either a before or
-after modifier. First, it is easy to modify the arguments being passed
-onto the original method in an around modifier. Second, you can decide
-to simply not call the original method at all, unlike with other
-modifiers. Finally, you can modify the return value with an around
-modifier.
+after modifier. It can modify the arguments being passed to the
+original method, and you can even decide to simply not call the
+original method at all. Finally, you can modify the return value with
+an around modifier.
 
 An around modifier receives the original method as its first argument,
 I<then> the object, and finally any arguments passed to the method.
@@ -213,9 +213,8 @@
 
 What makes this combination of C<augment> and C<inner()> special is
 that it allows us to have methods which are called from parent (least
-specific) to child (most specific). This inverts the normal order,
-where the child's method is called first, and it in turn will call C<<
-$self->SUPER::method >> to call the parent.
+specific) to child (most specific). This inverts the normal
+inheritance pattern.
 
 Note that in C<Report::IncomeAndExpenses> we call C<inner()> again. If
 the object is an instance of C<Report::IncomeAndExpenses> then this
@@ -263,7 +262,7 @@
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2008 by Infinity Interactive, Inc.
+Copyright 2008-2009 by Infinity Interactive, Inc.
 
 L<http://www.iinteractive.com>