need to use Moose in this example

[gitmo/Moose.git] / lib / Moose / Cookbook / Extending / ExtensionOverview.pod

diff --git a/lib/Moose/Cookbook/Extending/ExtensionOverview.pod b/lib/Moose/Cookbook/Extending/ExtensionOverview.pod
index 553b9be..20e2a77 100644 (file)
--- a/lib/Moose/Cookbook/Extending/ExtensionOverview.pod
+++ b/lib/Moose/Cookbook/Extending/ExtensionOverview.pod
@@ -221,6 +221,7 @@ And then the consumer of your extension can use your C<embiggen> sub:
 
   package Consumer;
 
+  use Moose;
   use MooseX::Embiggen;
 
   extends 'Thing';
@@ -235,9 +236,10 @@ B<Note: We strongly recommend that you provide your extension as a set of
 roles whenever possible>.
 
 Moose does not provide any simple APIs for consumers to use a subclass
-extension, except for attribute metaclasses. The attribute declaration
-options include a C<metaclass> option a consumer of your extension can
-use to specify your subclass.
+extension, except for class and attribute metaclasses. The attribute
+declaration options include a C<metaclass> option a consumer of your extension
+can use to specify your subclass, and class metaclasses can be passed via the
+C<-metaclass> import option when you C<use Moose>.
 
 This is one reason why implementing an extension as a subclass can be
 a poor choice. However, you can force the use of certain subclasses at
@@ -274,8 +276,13 @@ subclasses:
       );
   }
 
-NOTE: Make sure that your C<init_meta> returns the metaclass object, just as
-C<< Moose->init_meta >> does.
+Note that there are several issues with this sort of extension mechanism, most
+notably that Moose only ever initializes the metaclass for a class once. This
+means that this extension must be loaded B<first>, before anything
+Moose-related touches the class. If you say C<use Moose; use
+MooseX::Embiggen;>, for instance, the extension will not be applied properly.
+There are very few reasons to implement an extension in this way; using
+metaclass traits is the right answer in nearly every case.
 
 =head1 LEGACY EXTENSION MECHANISMS