X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FMoose%2FSpec%2FRole.pod;h=b44667a7fcad36243512c0a3d1311fe1dc215548;hb=8abe9636abcd0945739dfeaf971eddbe1fd0cc9e;hp=034d0f63f8199d4ace407f5a07a644f178cd9aef;hpb=24a8fe99b0ddd93f7af15e1827c46408d8b01ab3;p=gitmo%2FMoose.git

diff --git a/lib/Moose/Spec/Role.pod b/lib/Moose/Spec/Role.pod
index 034d0f6..b44667a 100644
--- a/lib/Moose/Spec/Role.pod
+++ b/lib/Moose/Spec/Role.pod
@@ -13,12 +13,42 @@ Moose::Spec::Role - Formal spec for Role behavior
 
 =item Excluded Roles
 
+A role can have a list of excluded roles, these are basically 
+roles that they shouldn't be composed with. This is not just 
+direct composition either, but also "inherited" composition. 
+
+This feature was taken from the Fortress language and is really 
+of most use when building a large set of role "building blocks"
+some of which should never be used together.
+
 =item Attributes
 
+A roles attributes are similar to those of a class, except that 
+they are not actually applied. This means that methods that are
+generated by an attributes accessor will not be generated in the
+role, but only created once the role is applied to a class.
+
 =item Methods
 
+These are the methods defined within the role. Simple as that.
+
 =item Required Methods
 
+A role can require a consuming class (or role) to provide a 
+given method. Failure to do so for classes is a fatal error, 
+while for roles it simply passes on the method requirement to 
+the consuming role.
+
+=item Required Attributes
+
+Just as a role can require methods, it can also require attributes.
+The requirement fufilling attribute must implement at least as much 
+as is required. That means, for instance, that if the role requires
+that the attribute be readonly, then it must at least have a reader
+and can also have a writer. It means that if the role requires that 
+the attribute be an ArrayRef, then it must either be an ArrayRef or 
+a subtype of an ArrayRef.
+
 =item Overriden Methods
 
 The C<override> and C<super> keywords are allowed in roles, but 
@@ -33,16 +63,72 @@ can never have a I<super> role.
 
 =item Method Modifiers
 
+These are the C<before>, C<around> and C<after> modifiers provided 
+in Moose classes. The difference here is that the modifiers are not 
+actually applied until the role is composed into a class (this is 
+just like attributes and the C<override> keyword).
+
+=back
+
+=head2 Role Composition
+
+=head3 Composing into a Class
+
+=over 4
+
+=item Excluded Roles
+
+=item Required Methods
+
+=item Required Attributes
+
+=item Attributes
+
+=item Methods
+
+=item Overriden methods
+
+=item Method Modifiers (before, around, after)
+
 =back
 
-=head2 Role to Role Composition Rules
+=head3 Composing into a Instance
 
-When a role is added to another role (using the C<with>
-keyword) the two roles are composed symmetrically. The 
-product of the composition is a third composite role.
+=head3 Composing into a Role 
 
 =over 4
 
+=item Excluded Roles
+
+=item Required Methods
+
+=item Required Attributes
+
+=item Attributes
+
+=item Methods
+
+=item Overriden methods
+
+=item Method Modifiers (before, around, after)
+
+=back
+
+=head3 Role Summation
+
+When multiple roles are added to another role (using the 
+C<with @roles> keyword) the roles are composed symmetrically. 
+The product of the composition is a composite role 
+(L<Moose::Meta::Role::Composite>).
+
+=over 4
+
+=item Excluded Roles
+
+=item Required Methods
+
+=item Required Attributes
+
 =item Attributes
 
 Attributes with the same name will conflict and are considered
@@ -110,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
@@ -162,7 +316,7 @@ Stevan Little E<lt>stevan@iinteractive.comE<gt>
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2007 by Infinity Interactive, Inc.
+Copyright 2007-2008 by Infinity Interactive, Inc.
 
 L<http://www.iinteractive.com>