X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FMoose%2FSpec%2FRole.pod;h=7dbfcfe0913f906bc42e37851c4b95f833c06518;hb=4223567e946b759fac471e1eef702396acb6fa54;hp=16bf4757dd213cb4bbd8cb6985b9c2a4e1631400;hpb=709c321c3bdc9a36769c9a2b24723b5315439fd3;p=gitmo%2FMoose.git

diff --git a/lib/Moose/Spec/Role.pod b/lib/Moose/Spec/Role.pod
index 16bf475..7dbfcfe 100644
--- a/lib/Moose/Spec/Role.pod
+++ b/lib/Moose/Spec/Role.pod
@@ -7,6 +7,8 @@ Moose::Spec::Role - Formal spec for Role behavior
 
 =head1 DESCRIPTION
 
+B<NOTE:> This document is currently incomplete.
+
 =head2 Components of a Role
 
 =over 4
@@ -72,7 +74,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 +94,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 +116,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 +198,93 @@ 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.
+
+Now here is another example of a (correct) type of overriding, this 
+time using the I<excludes> option.
+
+    package Role::Foo;
+    use Moose::Role;
+    
+    sub foo { ... }
+    
+    package Role::FooBar;
+    use Moose::Role;
+    
+    with 'Role::Foo' => { excludes => 'foo' };
+    
+    sub foo { ... }
+    sub bar { ... }
+
+By specifically excluding the C<foo> method during composition, 
+we allow B<Role::FooBar> to define it's own version of C<foo>.
+
+=back
+
 =head1 SEE ALSO
 
 =over 4