Explicit documentation on modifying role methods

lib/MooseX/Declare.pm

@@ -101,6 +101,17 @@ Sets a superclass for the class being declared.
 
 Applies a role or roles to the class being declared.
 
+(The actual application of the role happens at the end of the class definition.
+If you want to modify methods provided by the role, you must apply it within
+the body of the class instead:
+
+    class Foo {
+      with 'Role';
+      around role_method { ... }
+    }
+
+See also L<MooseX::Declare::Syntax::Keyword::With>.)
+
 =item is mutable
 
     class Foo is mutable { ... }
@@ -135,6 +146,17 @@ It's possible to specify options for roles:
 
 Applies a role to the role being declared.
 
+(The actual application of the role happens at the end of the role definition.
+If you want to modify methods provided by the consumed role, you must apply it
+within the body of the role instead:
+
+    role Foo {
+      with 'Bar';
+      around bar_method { ... }
+    }
+
+See also L<MooseX::Declare::Syntax::Keyword::With>.)
+
 =back
 
 =head2 before / after / around / override / augment

lib/MooseX/Declare/Syntax/Keyword/With.pm

@@ -23,6 +23,20 @@ differs from the C<with>-option of the C<class> and C<role> keywords in that it
 applies the roles immediately instead of defering application until the end of
 the class- or role-definition.
 
+In particular, this allows you to modify methods provided by the role.  For
+example:
+
+  role Role {
+    requires 'class_method';
+    method role_method { ... }
+  }
+
+  class Foo {
+    method class_method { ... }  # first, declare required methods
+    with 'Role';                 # then, apply the role
+    around role_method { ... }   # finally, modify the role's methods
+  }
+
 It also differs slightly from the C<with> provided by L<Moose|Moose> in that it
 expands relative role names (C<::Foo>) according to the currenc C<namespace>.