Revised basics recipe 7.

Moved info about immutable & overridden new() to Classes manual

diff --git a/lib/Moose/Cookbook/Basics/Recipe7.pod b/lib/Moose/Cookbook/Basics/Recipe7.pod
index 4b2047d..b3fabe0 100644 (file)
--- a/lib/Moose/Cookbook/Basics/Recipe7.pod
+++ b/lib/Moose/Cookbook/Basics/Recipe7.pod
@@ -17,33 +17,21 @@ Moose::Cookbook::Basics::Recipe7 - Making Moose fast with immutable
 
 =head1 DESCRIPTION
 
-The Moose metaclass API provides a method C<make_immutable()>. At a
-high level, this calling this method does two things to your
-class. One, it makes it faster. In particular, object construction and
-accessors are effectively "inlined" in your class, and no longer go
-through the meta-object system.
+The Moose metaclass API provides a C<make_immutable()> method. Calling
+this method does two things to your class. First, it makes it
+faster. In particular, object construction and destruction are
+effectively "inlined" in your class, and no longer invokes the meta
+API.
 
-Second, you can no longer make changes via the metaclass API such as
-adding attributes. In practice, this won't be a problem, as you don't
-usually need to do this at runtime after first loading the class.
-
-=head2 Immutabilization and C<new()>
-
-If you override C<new()> in your class, then the immutabilization code
-will not be able to provide an optimized constructor for your
-class. Instead, consider providing a C<BUILD()> method. You can
-probably do the same thing in a C<BUILD()> method.
-
-Alternately, if you really need to provide a different C<new()>, you
-can also provide your own immutabilization method.
-
-Discussing this is beyond the scope of this recipe, however.
+Second, you can no longer make changes via the metaclass API, such as
+adding attributes. In practice, this won't be a problem, as you rarely
+need to do this after first loading the class.
 
 =head1 CONCLUSION
 
 We strongly recommend you make your classes immutable. It makes your
-code much faster, basically for free. This will be especially
-noticeable when creating many objects or calling accessors frequently.
+code much faster, with a small compile-time cost. This will be
+especially noticeable when creating many object.
 
 =head1 AUTHOR
 

diff --git a/lib/Moose/Manual/Classes.pod b/lib/Moose/Manual/Classes.pod
index 13ccd73..f2cd397 100644 (file)
--- a/lib/Moose/Manual/Classes.pod
+++ b/lib/Moose/Manual/Classes.pod
@@ -103,6 +103,18 @@ class's metaclass object.
 
   __PACKAGE__->meta->make_immutable;
 
+=head2 Immutabilization and C<new()>
+
+If you override C<new()> in your class, then the immutabilization code
+will not be able to provide an optimized constructor for your
+class. Instead, you should use C<BUILD()> method, which will be called
+from the inlined constructor.
+
+Alternately, if you really need to provide a different C<new()>, you
+can also provide your own immutabilization method. Doing so requires
+extending the Moose metaclasses, and is well beyond the scope of this
+manual.
+
 =head1 AUTHOR
 
 Dave Rolsky E<lt>autarch@urth.orgE<gt>