X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FMoose%2FCookbook.pod;h=0f106ca07236703b053c40c0f5fb1c7ae4ca8703;hb=b5a10bf862744c97e1e9e0fb9ebb57366ac42e19;hp=67f6669f1c4ba63a9dc0806349a96eb7c760b032;hpb=a8b3fe6201d7f6ec5d22a3c09331cfae97633de0;p=gitmo%2FMoose.git

diff --git a/lib/Moose/Cookbook.pod b/lib/Moose/Cookbook.pod
index 67f6669..0f106ca 100644
--- a/lib/Moose/Cookbook.pod
+++ b/lib/Moose/Cookbook.pod
@@ -19,6 +19,11 @@ for common questions and problems people have with Moose.
 
 =head2 Basic Moose
 
+These recipes will give you a good idea of what Moose is capable,
+starting with simple attribute declaration, and moving on to more
+powerful features like laziness, types, type coercion, method
+modifiers, and more.
+
 =over 4
 
 =item L<Moose::Cookbook::Basics::Recipe1> - The (always classic) B<Point> example
@@ -34,7 +39,7 @@ modifier in a subclass.
 
 Demonstrates several attribute features, including types, weak
 references, predicates ("does this object have a foo?"), defaults, and
-lazy attribute construction.
+lazy attribute uction.
 
 =item L<Moose::Cookbook::Basics::Recipe4> - Subtypes, and modeling a simple B<Company> class hierarchy
 
@@ -68,13 +73,15 @@ provide a default attribute value.
 
 =item L<Moose::Cookbook::Basics::Recipe10> - Operator overloading, subtypes, and coercion
 
-Demonstrates using operator overloading, coercion, and sub types to
+Demonstrates using operator overloading, coercion, and subtypes to
 model how eye color is determined during reproduction.
 
 =back
 
 =head2 Moose Roles
 
+These recipes will show you how to use Moose roles.
+
 =over 4
 
 =item L<Moose::Cookbook::Role::Recipe1> - The Moose::Role example
@@ -98,40 +105,103 @@ I<abstract goes here>
 
 =head2 Meta Moose
 
+These recipes show you how to write your own meta classes, which lets
+you extend the object system provide by Moose.
+
 =over 4
 
 =item L<Moose::Cookbook::Meta::Recipe1> - Welcome to the meta-world (Why Go Meta?)
 
-I<abstract goes here>
+If you're wondering what all this "meta" stuff is, and why you should
+care about it, read this "recipe".
 
-=item L<Moose::Cookbook::Meta::Recipe2> - The meta-attribute example
+=item L<Moose::Cookbook::Meta::Recipe2> - A meta-attribute, attributes with labels
 
 One way to extend Moose is to provide your own attribute
 metaclasses. Attribute metaclasses let you extend attribute
 declarations (with C<has>) and behavior to provide additional
 attribute functionality.
 
-=item L<Moose::Cookbook::Meta::Recipe3> - The meta-attribute trait example
+=item L<Moose::Cookbook::Meta::Recipe3> - Labels implemented via attribute traits
 
 Extending Moose's attribute metaclass is a great way to add
 functionality. However, attributes can only have one metaclass.
 Applying roles to the attribute metaclass lets you provide
 composable attribute functionality.
 
-=item L<Moose::Cookbook::Meta::Recipe4> - The meta-instance example (TODO)
+=item L<Moose::Cookbook::Meta::Recipe4> - Adding a "table" attribute to the metaclass
 
-I<abstract goes here>
+If you want to store more information about your classes, you'll have
+to extend C<Moose::Meta::Class>. Doing so is simple, but you'll
+probably also want to provide some sugar, so see
+L<Moose::Cookbook::Extending::Recipe2> as well.
+
+=item L<Moose::Cookbook::Meta::Recipe5> - The "table" attribute implemented as a metaclass trait
+
+This example takes the class metaclass we saw in the previous recipe
+and reimplements it as a metaclass trait.
 
-=item L<Moose::Cookbook::Recipe24> - The meta-class example (TODO)
+=item L<Moose::Cookbook::Meta::Recipe6> - Hooking into the immutabilization system (TODO)
+
+Moose has a feature known as "immutabilization". By calling C<<
+__PACKAGE__->meta()->make_immutable() >> after defining your class
+(attributes, roles, etc), you tell Moose to optimize things like
+object creation, attribute access, and so on.
+
+If you are creating your own metaclasses, you may need to hook into
+the immutabilization system. This cuts across a number of spots,
+including the metaclass class, meta method classes, and possibly the
+meta-instance class as well.
+
+This recipe shows you how to write extensions which immutabilize
+properly.
+
+=item L<Moose::Cookbook::Meta::Recipe7> - I<meta-instance> (TODO)
 
 I<abstract goes here>
 
 =back
 
+=head2 Extending Moose
+
+These recipes cover some more ways to extend Moose, and will be useful
+if you plan to write your own C<MooseX> module.
+
+=over 4
+
+=item L<Moose::Cookbook::Extending::Recipe1> - Moose extension overview
+
+There are quite a number of ways to extend Moose. This recipe explains
+provides an overview of each method, and provides recommendations for
+when each is appropriate.
+
+=item L<Moose::Cookbook::Extending::Recipe2> - Providing a base object class role (TODO)
+
+Many base object class extensions can be implemented as roles. This
+example shows how to provide a base object class debugging role.
+
+=item L<Moose::Cookbook::Extending::Recipe3> - Providing an alternate base object class
+
+You may find that you want to provide an alternate base object class
+along with a meta extension, or maybe you just want to add some
+functionality to all your classes without typing C<extends
+'MyApp::Base'> over and over.
+
+=item L<Moose::Cookbook::Extending::Recipe4> - Acting like Moose.pm and providing sugar Moose-style
+
+This recipe shows how to provide a replacement for C<Moose.pm>. You
+may want to do this as part of the API for a C<MooseX> module,
+especially if you want to default to a new metaclass class or base
+object class.
+
+=back
+
 =head1 SNACKS
 
 =over 4
 
+=item L<Moose::Cookbook::Snack::Keywords>
+
 =item L<Moose::Cookbook::Snack::Types>
 
 =back