When applying a role to a class and some methods are missing (or are

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

diff --git a/lib/Moose/Spec/Role.pod b/lib/Moose/Spec/Role.pod
index b44667a..7dbfcfe 100644 (file)
--- 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
@@ -262,6 +264,25 @@ 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