for use with Class-MOP-initializer

[gitmo/Moose.git] / lib / Moose / Spec / Role.pod

diff --git a/lib/Moose/Spec/Role.pod b/lib/Moose/Spec/Role.pod
index 16bf475..b44667a 100644 (file)
--- a/lib/Moose/Spec/Role.pod
+++ b/lib/Moose/Spec/Role.pod
@@ -72,7 +72,7 @@ just like attributes and the C<override> keyword).
 
 =head2 Role Composition
 
-=head3 Composing into a Role 
+=head3 Composing into a Class
 
 =over 4
 
@@ -92,7 +92,9 @@ just like attributes and the C<override> keyword).
 
 =back
 
-=head3 Composing into a Class
+=head3 Composing into a Instance
+
+=head3 Composing into a Role 
 
 =over 4
 
@@ -112,9 +114,7 @@ just like attributes and the C<override> keyword).
 
 =back
 
-=head3 Composing into a Instance  
-
-=head2 Role Summation
+=head3 Role Summation
 
 When multiple roles are added to another role (using the 
 C<with @roles> keyword) the roles are composed symmetrically. 
@@ -196,6 +196,74 @@ is the key.
 
 =back
 
+=head3 Composition Edge Cases
+
+This is a just a set of complex edge cases which can easily get 
+confused. This attempts to clarify those cases and provide an 
+explination of what is going on in them.
+
+=over 4
+
+=item Role Method Overriding
+
+Many people want to "override" methods in roles they are consuming.
+This works fine for classes, since the local class method is favored
+over the role method. However in roles it is trickier, this is because 
+conflicts result in neither method being chosen and the method being 
+"required" instead. 
+
+Here is an example of this (incorrect) type of overriding.
+
+    package Role::Foo;
+    use Moose::Role;
+
+    sub foo { ... }
+
+    package Role::FooBar;
+    use Moose::Role;
+
+    with 'Role::Foo';
+
+    sub foo { ... }
+    sub bar { ... }
+
+Here the C<foo> methods conflict and the Role::FooBar now requires a 
+class or role consuming it to implement C<foo>. This is very often not
+what the user wants.
+
+Now here is an example of the (correct) type of overriding, only it is
+not overriding at all, as is explained in the text below.
+
+    package Role::Foo;
+    use Moose::Role;
+
+    sub foo { ... }
+
+    package Role::Bar;
+    use Moose::Role;
+
+    sub foo { ... }
+    sub bar { ... }
+
+    package Role::FooBar;
+    use Moose::Role;
+
+    with 'Role::Foo', 'Role::Bar';
+    
+    sub foo { ... }
+
+This works because the combination of Role::Foo and Role::Bar produce
+a conflict with the C<foo> method. This conflict results in the 
+composite role (that was created by the combination of Role::Foo 
+and Role::Bar using the I<with> keyword) having a method requirement 
+of C<foo>. The Role::FooBar then fufills this requirement. 
+
+It is important to note that Role::FooBar is simply fufilling the 
+required C<foo> method, and **NOT** overriding C<foo>. This is an 
+important distinction to make.
+
+=back
+
 =head1 SEE ALSO
 
 =over 4