Add first draft of classes manual document

diff --git a/lib/Moose/Manual/Classes.pod b/lib/Moose/Manual/Classes.pod
new file mode 100644 (file)
index 0000000..b4081ae
--- /dev/null
+++ b/lib/Moose/Manual/Classes.pod
@@ -0,0 +1,141 @@
+=pod
+
+=head1 NAME
+
+Moose::Manual::Classes - Making your classes use Moose (and subclassing)
+
+=head1 USING MOOSE
+
+Using Moose is very simple, you just C<use Moose>:
+
+  package Person;
+
+  use Moose;
+
+That's it, you've now made a Moose-based class!
+
+There's actually a lot going on here under the hood, so let's step
+through it. The L<Moose> package does several things when you load it.
+
+When you load Moose, you get a bunch of sugar functions exported into
+your class. These include things like C<extends>, C<has>, C<with>, and
+more. These functions are what you use to define your class. For
+example, you might define an attribute ...
+
+  package Person;
+
+  use Moose;
+
+  has 'ssn' => ( is => 'rw' );
+
+Attributes are described in the L<Moose::Manual::Attributes>
+documentation.
+
+Loading Moose in your class also turns on the C<strict> and
+C<warnings> pragmas in your class for you.
+
+It also creates a L<Moose::Meta::Class> object for your class. This
+metaclass object is now available by calling a C<meta> method on your
+class, for example C<< Person->meta >>.
+
+The metaclass object an introspection API for your class. It is also
+used by Moose itself under the hood to add attributes, define parent
+classes, and so on. In fact, all of Moose's sugar does the real work
+by calling methods on this metaclass object (and other meta level
+objects).
+
+When you load Moose, your class will become a subclass of
+L<Moose::Object>. The L<Moose::Object> class provides a default
+constructor, destructor, as well as object construction helper
+methods. You can read more about this in the
+L<Moose::Manual::Construction> document.
+
+As a convenience, Moose creates a new class type with the name of your
+class, by calling the C<class_type> function in
+L<Moose::Util::Constraints>. See the L<Moose::Manual::Types> document
+for more about types.
+
+=head1 SUBCLASSING
+
+Moose provides a simple sugar function for declaring your parent
+classes, C<extends>:
+
+  package User;
+
+  use Moose;
+
+  extends 'Person';
+
+  has 'username' => ( is => 'rw' );
+
+When you call extends, Moose takes the class(es) you provide and makes
+those the parent of the current class. Note, that each call to
+C<extends> will I<reset> your parents, so for multiple inheritance you
+should provide all you parents at once, C<extends 'Foo', 'Bar'>.
+
+You can use Moose to extend a non-Moose parent. However, when you do
+this, you will inherit the parent class's constructor (assuming it is
+also called C<new>). In that case, you will have to take care of
+initializing attributes manually, either in the parent's constructor,
+or in your subclass, and you will generally lose a lot of Moose magic.
+
+=head1 NO MOOSE
+
+Moose also allows you to remove its sugar functions from your class's
+namespace. We recommend that you take advantage of this feature, since
+it just makes your classes "cleaner". You can do this by simply adding
+C<no Moose> at the end of your module file.
+
+What this does is delete the functions from your class's namespace, so
+that C<< Person->can('has') >> will no longer return true.
+
+=head1 MAKING IT FASTER
+
+Moose has a feature called "immutabilization" that you can use to
+greatly speed up your classes at runtime. However, using it does incur
+a cost when your class is first being loaded. When you make your class
+immutable you tell Moose that you will not be changing it,
+specifically not adding any attributes, methods, roles, etc.
+
+This allows Moose to generate code specific to your class for its
+constructor and other methods, making object construction much
+faster. It also makes some of the introspection methods faster as
+well.
+
+To make your class immutable you simply call C<make_immutable> on your
+class's metaclass object.
+
+=head1 RECOMMENDATIONS
+
+We recommend that you end your Moose class definitions by removing the
+Moose sugar and making your class immutable.
+
+  package Person;
+
+  use Moose;
+
+  # extends, roles, attributes, etc.
+
+  # methods
+
+  no Moose;
+
+  __PACKAGE__->meta->make_immutable;
+
+  1;
+
+=head1 AUTHOR
+
+Dave Rolsky E<lt>autarch@urth.orgE<gt>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2008 by Infinity Interactive, Inc.
+
+L<http://www.iinteractive.com>
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
+
+=cut
+