stop encouraging wrapping BUILDALL, it's a bad idea

diff --git a/lib/Moose/Cookbook/Extending/Recipe2.pod b/lib/Moose/Cookbook/Extending/Recipe2.pod
index 03c3909..c1a8457 100644 (file)
--- a/lib/Moose/Cookbook/Extending/Recipe2.pod
+++ b/lib/Moose/Cookbook/Extending/Recipe2.pod
@@ -29,7 +29,8 @@ use Test::Requires {
 
   use Moose::Role;
 
-  after 'BUILDALL' => sub {
+  sub BUILD {}
+  after BUILD => sub {
       my $self = shift;
 
       warn "Made a new " . ( ref $self ) . " object\n";
@@ -63,6 +64,19 @@ C<setup_import_methods> for us, since we passed the C<base_class_roles>
 parameter. The generated C<init_meta> will in turn call
 L<Moose::Util::MetaRole::apply_base_class_roles|Moose::Util::MetaRole/apply_base_class_roles>.
 
+  sub BUILD {}
+  after BUILD => sub {
+      ...
+  };
+
+Due to the way role composition currently works, if the class that a role is
+composed into contains a C<BUILD> method, then that will override the C<BUILD>
+method in any roles it composes, which is typically not what you want. Using a
+method modifier on C<BUILD> avoids this issue, since method modifiers compose
+together rather than being overridden. Method modifiers require that a method
+exists in order to wrap, however, so we also provide a stub method to wrap if
+no C<BUILD> method exists in the class.
+
 =begin testing
 
 {